Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1 | USING THE IJG JPEG LIBRARY |
| 2 | |
DRC | a73e870 | 2012-12-31 02:52:30 +0000 | [diff] [blame] | 3 | This file was part of the Independent JPEG Group's software: |
Guido Vollbeding | 5829cb2 | 2012-01-15 00:00:00 +0000 | [diff] [blame] | 4 | Copyright (C) 1994-2011, Thomas G. Lane, Guido Vollbeding. |
DRC | da13af6 | 2014-05-18 17:52:06 +0000 | [diff] [blame] | 5 | libjpeg-turbo Modifications: |
DRC | eb32cc1 | 2015-06-25 03:44:36 +0000 | [diff] [blame] | 6 | Copyright (C) 2010, 2014, 2015, D. R. Commander. |
| 7 | Copyright (C) 2015, Google, Inc. |
DRC | 7e3acc0 | 2015-10-10 10:25:46 -0500 | [diff] [blame] | 8 | For conditions of distribution and use, see the accompanying README.ijg file. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 9 | |
| 10 | |
| 11 | This file describes how to use the IJG JPEG library within an application |
| 12 | program. Read it if you want to write a program that uses the library. |
| 13 | |
| 14 | The file example.c provides heavily commented skeleton code for calling the |
| 15 | JPEG library. Also see jpeglib.h (the include file to be used by application |
| 16 | programs) for full details about data structures and function parameter lists. |
| 17 | The library source code, of course, is the ultimate reference. |
| 18 | |
| 19 | Note that there have been *major* changes from the application interface |
| 20 | presented by IJG version 4 and earlier versions. The old design had several |
| 21 | inherent limitations, and it had accumulated a lot of cruft as we added |
| 22 | features while trying to minimize application-interface changes. We have |
| 23 | sacrificed backward compatibility in the version 5 rewrite, but we think the |
| 24 | improvements justify this. |
| 25 | |
| 26 | |
| 27 | TABLE OF CONTENTS |
| 28 | ----------------- |
| 29 | |
| 30 | Overview: |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 31 | Functions provided by the library |
| 32 | Outline of typical usage |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 33 | Basic library usage: |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 34 | Data formats |
| 35 | Compression details |
| 36 | Decompression details |
| 37 | Mechanics of usage: include files, linking, etc |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 38 | Advanced features: |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 39 | Compression parameter selection |
| 40 | Decompression parameter selection |
| 41 | Special color spaces |
| 42 | Error handling |
| 43 | Compressed data handling (source and destination managers) |
| 44 | I/O suspension |
| 45 | Progressive JPEG support |
| 46 | Buffered-image mode |
| 47 | Abbreviated datastreams and multiple images |
| 48 | Special markers |
| 49 | Raw (downsampled) image data |
| 50 | Really raw data: DCT coefficients |
| 51 | Progress monitoring |
| 52 | Memory management |
| 53 | Memory usage |
| 54 | Library compile-time options |
| 55 | Portability considerations |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 56 | |
| 57 | You should read at least the overview and basic usage sections before trying |
| 58 | to program with the library. The sections on advanced features can be read |
| 59 | if and when you need them. |
| 60 | |
| 61 | |
| 62 | OVERVIEW |
| 63 | ======== |
| 64 | |
| 65 | Functions provided by the library |
| 66 | --------------------------------- |
| 67 | |
| 68 | The IJG JPEG library provides C code to read and write JPEG-compressed image |
| 69 | files. The surrounding application program receives or supplies image data a |
| 70 | scanline at a time, using a straightforward uncompressed image format. All |
| 71 | details of color conversion and other preprocessing/postprocessing can be |
| 72 | handled by the library. |
| 73 | |
| 74 | The library includes a substantial amount of code that is not covered by the |
| 75 | JPEG standard but is necessary for typical applications of JPEG. These |
| 76 | functions preprocess the image before JPEG compression or postprocess it after |
| 77 | decompression. They include colorspace conversion, downsampling/upsampling, |
| 78 | and color quantization. The application indirectly selects use of this code |
| 79 | by specifying the format in which it wishes to supply or receive image data. |
| 80 | For example, if colormapped output is requested, then the decompression |
| 81 | library automatically invokes color quantization. |
| 82 | |
| 83 | A wide range of quality vs. speed tradeoffs are possible in JPEG processing, |
| 84 | and even more so in decompression postprocessing. The decompression library |
| 85 | provides multiple implementations that cover most of the useful tradeoffs, |
| 86 | ranging from very-high-quality down to fast-preview operation. On the |
| 87 | compression side we have generally not provided low-quality choices, since |
| 88 | compression is normally less time-critical. It should be understood that the |
| 89 | low-quality modes may not meet the JPEG standard's accuracy requirements; |
| 90 | nonetheless, they are useful for viewers. |
| 91 | |
| 92 | A word about functions *not* provided by the library. We handle a subset of |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 93 | the ISO JPEG standard; most baseline, extended-sequential, and progressive |
| 94 | JPEG processes are supported. (Our subset includes all features now in common |
| 95 | use.) Unsupported ISO options include: |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 96 | * Hierarchical storage |
| 97 | * Lossless JPEG |
| 98 | * DNL marker |
| 99 | * Nonintegral subsampling ratios |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 100 | We support both 8- and 12-bit data precision, but this is a compile-time |
| 101 | choice rather than a run-time choice; hence it is difficult to use both |
| 102 | precisions in a single application. |
| 103 | |
| 104 | By itself, the library handles only interchange JPEG datastreams --- in |
| 105 | particular the widely used JFIF file format. The library can be used by |
| 106 | surrounding code to process interchange or abbreviated JPEG datastreams that |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 107 | are embedded in more complex file formats. (For example, this library is |
| 108 | used by the free LIBTIFF library to support JPEG compression in TIFF.) |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 109 | |
| 110 | |
| 111 | Outline of typical usage |
| 112 | ------------------------ |
| 113 | |
| 114 | The rough outline of a JPEG compression operation is: |
| 115 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 116 | Allocate and initialize a JPEG compression object |
| 117 | Specify the destination for the compressed data (eg, a file) |
| 118 | Set parameters for compression, including image size & colorspace |
| 119 | jpeg_start_compress(...); |
| 120 | while (scan lines remain to be written) |
| 121 | jpeg_write_scanlines(...); |
| 122 | jpeg_finish_compress(...); |
| 123 | Release the JPEG compression object |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 124 | |
| 125 | A JPEG compression object holds parameters and working state for the JPEG |
| 126 | library. We make creation/destruction of the object separate from starting |
| 127 | or finishing compression of an image; the same object can be re-used for a |
| 128 | series of image compression operations. This makes it easy to re-use the |
| 129 | same parameter settings for a sequence of images. Re-use of a JPEG object |
| 130 | also has important implications for processing abbreviated JPEG datastreams, |
| 131 | as discussed later. |
| 132 | |
| 133 | The image data to be compressed is supplied to jpeg_write_scanlines() from |
| 134 | in-memory buffers. If the application is doing file-to-file compression, |
| 135 | reading image data from the source file is the application's responsibility. |
| 136 | The library emits compressed data by calling a "data destination manager", |
| 137 | which typically will write the data into a file; but the application can |
| 138 | provide its own destination manager to do something else. |
| 139 | |
| 140 | Similarly, the rough outline of a JPEG decompression operation is: |
| 141 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 142 | Allocate and initialize a JPEG decompression object |
| 143 | Specify the source of the compressed data (eg, a file) |
| 144 | Call jpeg_read_header() to obtain image info |
| 145 | Set parameters for decompression |
| 146 | jpeg_start_decompress(...); |
| 147 | while (scan lines remain to be read) |
| 148 | jpeg_read_scanlines(...); |
| 149 | jpeg_finish_decompress(...); |
| 150 | Release the JPEG decompression object |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 151 | |
| 152 | This is comparable to the compression outline except that reading the |
| 153 | datastream header is a separate step. This is helpful because information |
| 154 | about the image's size, colorspace, etc is available when the application |
| 155 | selects decompression parameters. For example, the application can choose an |
| 156 | output scaling ratio that will fit the image into the available screen size. |
| 157 | |
| 158 | The decompression library obtains compressed data by calling a data source |
| 159 | manager, which typically will read the data from a file; but other behaviors |
| 160 | can be obtained with a custom source manager. Decompressed data is delivered |
| 161 | into in-memory buffers passed to jpeg_read_scanlines(). |
| 162 | |
| 163 | It is possible to abort an incomplete compression or decompression operation |
| 164 | by calling jpeg_abort(); or, if you do not need to retain the JPEG object, |
| 165 | simply release it by calling jpeg_destroy(). |
| 166 | |
| 167 | JPEG compression and decompression objects are two separate struct types. |
| 168 | However, they share some common fields, and certain routines such as |
| 169 | jpeg_destroy() can work on either type of object. |
| 170 | |
| 171 | The JPEG library has no static variables: all state is in the compression |
| 172 | or decompression object. Therefore it is possible to process multiple |
| 173 | compression and decompression operations concurrently, using multiple JPEG |
| 174 | objects. |
| 175 | |
| 176 | Both compression and decompression can be done in an incremental memory-to- |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 177 | memory fashion, if suitable source/destination managers are used. See the |
| 178 | section on "I/O suspension" for more details. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 179 | |
| 180 | |
| 181 | BASIC LIBRARY USAGE |
| 182 | =================== |
| 183 | |
| 184 | Data formats |
| 185 | ------------ |
| 186 | |
| 187 | Before diving into procedural details, it is helpful to understand the |
| 188 | image data format that the JPEG library expects or returns. |
| 189 | |
| 190 | The standard input image format is a rectangular array of pixels, with each |
Thomas G. Lane | 489583f | 1996-02-07 00:00:00 +0000 | [diff] [blame] | 191 | pixel having the same number of "component" or "sample" values (color |
| 192 | channels). You must specify how many components there are and the colorspace |
| 193 | interpretation of the components. Most applications will use RGB data |
| 194 | (three components per pixel) or grayscale data (one component per pixel). |
| 195 | PLEASE NOTE THAT RGB DATA IS THREE SAMPLES PER PIXEL, GRAYSCALE ONLY ONE. |
| 196 | A remarkable number of people manage to miss this, only to find that their |
| 197 | programs don't work with grayscale JPEG files. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 198 | |
Thomas G. Lane | 489583f | 1996-02-07 00:00:00 +0000 | [diff] [blame] | 199 | There is no provision for colormapped input. JPEG files are always full-color |
| 200 | or full grayscale (or sometimes another colorspace such as CMYK). You can |
| 201 | feed in a colormapped image by expanding it to full-color format. However |
| 202 | JPEG often doesn't work very well with source data that has been colormapped, |
| 203 | because of dithering noise. This is discussed in more detail in the JPEG FAQ |
DRC | 7e3acc0 | 2015-10-10 10:25:46 -0500 | [diff] [blame] | 204 | and the other references mentioned in the README.ijg file. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 205 | |
| 206 | Pixels are stored by scanlines, with each scanline running from left to |
| 207 | right. The component values for each pixel are adjacent in the row; for |
| 208 | example, R,G,B,R,G,B,R,G,B,... for 24-bit RGB color. Each scanline is an |
| 209 | array of data type JSAMPLE --- which is typically "unsigned char", unless |
| 210 | you've changed jmorecfg.h. (You can also change the RGB pixel layout, say |
| 211 | to B,G,R order, by modifying jmorecfg.h. But see the restrictions listed in |
| 212 | that file before doing so.) |
| 213 | |
| 214 | A 2-D array of pixels is formed by making a list of pointers to the starts of |
| 215 | scanlines; so the scanlines need not be physically adjacent in memory. Even |
| 216 | if you process just one scanline at a time, you must make a one-element |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 217 | pointer array to conform to this structure. Pointers to JSAMPLE rows are of |
| 218 | type JSAMPROW, and the pointer to the pointer array is of type JSAMPARRAY. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 219 | |
| 220 | The library accepts or supplies one or more complete scanlines per call. |
| 221 | It is not possible to process part of a row at a time. Scanlines are always |
| 222 | processed top-to-bottom. You can process an entire image in one call if you |
| 223 | have it all in memory, but usually it's simplest to process one scanline at |
| 224 | a time. |
| 225 | |
| 226 | For best results, source data values should have the precision specified by |
| 227 | BITS_IN_JSAMPLE (normally 8 bits). For instance, if you choose to compress |
| 228 | data that's only 6 bits/channel, you should left-justify each value in a |
| 229 | byte before passing it to the compressor. If you need to compress data |
| 230 | that has more than 8 bits/channel, compile with BITS_IN_JSAMPLE = 12. |
| 231 | (See "Library compile-time options", later.) |
| 232 | |
Thomas G. Lane | 489583f | 1996-02-07 00:00:00 +0000 | [diff] [blame] | 233 | |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 234 | The data format returned by the decompressor is the same in all details, |
Thomas G. Lane | 489583f | 1996-02-07 00:00:00 +0000 | [diff] [blame] | 235 | except that colormapped output is supported. (Again, a JPEG file is never |
| 236 | colormapped. But you can ask the decompressor to perform on-the-fly color |
| 237 | quantization to deliver colormapped output.) If you request colormapped |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 238 | output then the returned data array contains a single JSAMPLE per pixel; |
| 239 | its value is an index into a color map. The color map is represented as |
| 240 | a 2-D JSAMPARRAY in which each row holds the values of one color component, |
| 241 | that is, colormap[i][j] is the value of the i'th color component for pixel |
| 242 | value (map index) j. Note that since the colormap indexes are stored in |
| 243 | JSAMPLEs, the maximum number of colors is limited by the size of JSAMPLE |
| 244 | (ie, at most 256 colors for an 8-bit JPEG library). |
| 245 | |
| 246 | |
| 247 | Compression details |
| 248 | ------------------- |
| 249 | |
| 250 | Here we revisit the JPEG compression outline given in the overview. |
| 251 | |
| 252 | 1. Allocate and initialize a JPEG compression object. |
| 253 | |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 254 | A JPEG compression object is a "struct jpeg_compress_struct". (It also has |
| 255 | a bunch of subsidiary structures which are allocated via malloc(), but the |
| 256 | application doesn't control those directly.) This struct can be just a local |
| 257 | variable in the calling routine, if a single routine is going to execute the |
| 258 | whole JPEG compression sequence. Otherwise it can be static or allocated |
| 259 | from malloc(). |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 260 | |
| 261 | You will also need a structure representing a JPEG error handler. The part |
| 262 | of this that the library cares about is a "struct jpeg_error_mgr". If you |
| 263 | are providing your own error handler, you'll typically want to embed the |
| 264 | jpeg_error_mgr struct in a larger structure; this is discussed later under |
| 265 | "Error handling". For now we'll assume you are just using the default error |
| 266 | handler. The default error handler will print JPEG error/warning messages |
| 267 | on stderr, and it will call exit() if a fatal error occurs. |
| 268 | |
| 269 | You must initialize the error handler structure, store a pointer to it into |
| 270 | the JPEG object's "err" field, and then call jpeg_create_compress() to |
| 271 | initialize the rest of the JPEG object. |
| 272 | |
| 273 | Typical code for this step, if you are using the default error handler, is |
| 274 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 275 | struct jpeg_compress_struct cinfo; |
| 276 | struct jpeg_error_mgr jerr; |
| 277 | ... |
| 278 | cinfo.err = jpeg_std_error(&jerr); |
| 279 | jpeg_create_compress(&cinfo); |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 280 | |
| 281 | jpeg_create_compress allocates a small amount of memory, so it could fail |
| 282 | if you are out of memory. In that case it will exit via the error handler; |
| 283 | that's why the error handler must be initialized first. |
| 284 | |
| 285 | |
| 286 | 2. Specify the destination for the compressed data (eg, a file). |
| 287 | |
| 288 | As previously mentioned, the JPEG library delivers compressed data to a |
| 289 | "data destination" module. The library includes one data destination |
| 290 | module which knows how to write to a stdio stream. You can use your own |
| 291 | destination module if you want to do something else, as discussed later. |
| 292 | |
| 293 | If you use the standard destination module, you must open the target stdio |
| 294 | stream beforehand. Typical code for this step looks like: |
| 295 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 296 | FILE * outfile; |
| 297 | ... |
| 298 | if ((outfile = fopen(filename, "wb")) == NULL) { |
| 299 | fprintf(stderr, "can't open %s\n", filename); |
| 300 | exit(1); |
| 301 | } |
| 302 | jpeg_stdio_dest(&cinfo, outfile); |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 303 | |
| 304 | where the last line invokes the standard destination module. |
| 305 | |
| 306 | WARNING: it is critical that the binary compressed data be delivered to the |
| 307 | output file unchanged. On non-Unix systems the stdio library may perform |
| 308 | newline translation or otherwise corrupt binary data. To suppress this |
| 309 | behavior, you may need to use a "b" option to fopen (as shown above), or use |
| 310 | setmode() or another routine to put the stdio stream in binary mode. See |
| 311 | cjpeg.c and djpeg.c for code that has been found to work on many systems. |
| 312 | |
| 313 | You can select the data destination after setting other parameters (step 3), |
| 314 | if that's more convenient. You may not change the destination between |
| 315 | calling jpeg_start_compress() and jpeg_finish_compress(). |
| 316 | |
| 317 | |
| 318 | 3. Set parameters for compression, including image size & colorspace. |
| 319 | |
| 320 | You must supply information about the source image by setting the following |
| 321 | fields in the JPEG object (cinfo structure): |
| 322 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 323 | image_width Width of image, in pixels |
| 324 | image_height Height of image, in pixels |
| 325 | input_components Number of color channels (samples per pixel) |
| 326 | in_color_space Color space of source image |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 327 | |
| 328 | The image dimensions are, hopefully, obvious. JPEG supports image dimensions |
| 329 | of 1 to 64K pixels in either direction. The input color space is typically |
| 330 | RGB or grayscale, and input_components is 3 or 1 accordingly. (See "Special |
| 331 | color spaces", later, for more info.) The in_color_space field must be |
| 332 | assigned one of the J_COLOR_SPACE enum constants, typically JCS_RGB or |
| 333 | JCS_GRAYSCALE. |
| 334 | |
| 335 | JPEG has a large number of compression parameters that determine how the |
| 336 | image is encoded. Most applications don't need or want to know about all |
| 337 | these parameters. You can set all the parameters to reasonable defaults by |
| 338 | calling jpeg_set_defaults(); then, if there are particular values you want |
| 339 | to change, you can do so after that. The "Compression parameter selection" |
| 340 | section tells about all the parameters. |
| 341 | |
| 342 | You must set in_color_space correctly before calling jpeg_set_defaults(), |
| 343 | because the defaults depend on the source image colorspace. However the |
| 344 | other three source image parameters need not be valid until you call |
| 345 | jpeg_start_compress(). There's no harm in calling jpeg_set_defaults() more |
| 346 | than once, if that happens to be convenient. |
| 347 | |
| 348 | Typical code for a 24-bit RGB source image is |
| 349 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 350 | cinfo.image_width = Width; /* image width and height, in pixels */ |
| 351 | cinfo.image_height = Height; |
| 352 | cinfo.input_components = 3; /* # of color components per pixel */ |
| 353 | cinfo.in_color_space = JCS_RGB; /* colorspace of input image */ |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 354 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 355 | jpeg_set_defaults(&cinfo); |
| 356 | /* Make optional parameter settings here */ |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 357 | |
| 358 | |
| 359 | 4. jpeg_start_compress(...); |
| 360 | |
| 361 | After you have established the data destination and set all the necessary |
| 362 | source image info and other parameters, call jpeg_start_compress() to begin |
| 363 | a compression cycle. This will initialize internal state, allocate working |
| 364 | storage, and emit the first few bytes of the JPEG datastream header. |
| 365 | |
| 366 | Typical code: |
| 367 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 368 | jpeg_start_compress(&cinfo, TRUE); |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 369 | |
| 370 | The "TRUE" parameter ensures that a complete JPEG interchange datastream |
| 371 | will be written. This is appropriate in most cases. If you think you might |
| 372 | want to use an abbreviated datastream, read the section on abbreviated |
| 373 | datastreams, below. |
| 374 | |
| 375 | Once you have called jpeg_start_compress(), you may not alter any JPEG |
| 376 | parameters or other fields of the JPEG object until you have completed |
| 377 | the compression cycle. |
| 378 | |
| 379 | |
| 380 | 5. while (scan lines remain to be written) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 381 | jpeg_write_scanlines(...); |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 382 | |
| 383 | Now write all the required image data by calling jpeg_write_scanlines() |
| 384 | one or more times. You can pass one or more scanlines in each call, up |
| 385 | to the total image height. In most applications it is convenient to pass |
| 386 | just one or a few scanlines at a time. The expected format for the passed |
| 387 | data is discussed under "Data formats", above. |
| 388 | |
| 389 | Image data should be written in top-to-bottom scanline order. The JPEG spec |
| 390 | contains some weasel wording about how top and bottom are application-defined |
| 391 | terms (a curious interpretation of the English language...) but if you want |
| 392 | your files to be compatible with everyone else's, you WILL use top-to-bottom |
| 393 | order. If the source data must be read in bottom-to-top order, you can use |
| 394 | the JPEG library's virtual array mechanism to invert the data efficiently. |
| 395 | Examples of this can be found in the sample application cjpeg. |
| 396 | |
| 397 | The library maintains a count of the number of scanlines written so far |
| 398 | in the next_scanline field of the JPEG object. Usually you can just use |
| 399 | this variable as the loop counter, so that the loop test looks like |
| 400 | "while (cinfo.next_scanline < cinfo.image_height)". |
| 401 | |
| 402 | Code for this step depends heavily on the way that you store the source data. |
| 403 | example.c shows the following code for the case of a full-size 2-D source |
| 404 | array containing 3-byte RGB pixels: |
| 405 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 406 | JSAMPROW row_pointer[1]; /* pointer to a single row */ |
| 407 | int row_stride; /* physical row width in buffer */ |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 408 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 409 | row_stride = image_width * 3; /* JSAMPLEs per row in image_buffer */ |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 410 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 411 | while (cinfo.next_scanline < cinfo.image_height) { |
| 412 | row_pointer[0] = & image_buffer[cinfo.next_scanline * row_stride]; |
| 413 | jpeg_write_scanlines(&cinfo, row_pointer, 1); |
| 414 | } |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 415 | |
| 416 | jpeg_write_scanlines() returns the number of scanlines actually written. |
| 417 | This will normally be equal to the number passed in, so you can usually |
| 418 | ignore the return value. It is different in just two cases: |
| 419 | * If you try to write more scanlines than the declared image height, |
| 420 | the additional scanlines are ignored. |
| 421 | * If you use a suspending data destination manager, output buffer overrun |
| 422 | will cause the compressor to return before accepting all the passed lines. |
| 423 | This feature is discussed under "I/O suspension", below. The normal |
| 424 | stdio destination manager will NOT cause this to happen. |
| 425 | In any case, the return value is the same as the change in the value of |
| 426 | next_scanline. |
| 427 | |
| 428 | |
| 429 | 6. jpeg_finish_compress(...); |
| 430 | |
| 431 | After all the image data has been written, call jpeg_finish_compress() to |
| 432 | complete the compression cycle. This step is ESSENTIAL to ensure that the |
| 433 | last bufferload of data is written to the data destination. |
| 434 | jpeg_finish_compress() also releases working memory associated with the JPEG |
| 435 | object. |
| 436 | |
| 437 | Typical code: |
| 438 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 439 | jpeg_finish_compress(&cinfo); |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 440 | |
| 441 | If using the stdio destination manager, don't forget to close the output |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 442 | stdio stream (if necessary) afterwards. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 443 | |
| 444 | If you have requested a multi-pass operating mode, such as Huffman code |
| 445 | optimization, jpeg_finish_compress() will perform the additional passes using |
| 446 | data buffered by the first pass. In this case jpeg_finish_compress() may take |
| 447 | quite a while to complete. With the default compression parameters, this will |
| 448 | not happen. |
| 449 | |
| 450 | It is an error to call jpeg_finish_compress() before writing the necessary |
| 451 | total number of scanlines. If you wish to abort compression, call |
| 452 | jpeg_abort() as discussed below. |
| 453 | |
| 454 | After completing a compression cycle, you may dispose of the JPEG object |
| 455 | as discussed next, or you may use it to compress another image. In that case |
| 456 | return to step 2, 3, or 4 as appropriate. If you do not change the |
| 457 | destination manager, the new datastream will be written to the same target. |
| 458 | If you do not change any JPEG parameters, the new datastream will be written |
| 459 | with the same parameters as before. Note that you can change the input image |
| 460 | dimensions freely between cycles, but if you change the input colorspace, you |
| 461 | should call jpeg_set_defaults() to adjust for the new colorspace; and then |
| 462 | you'll need to repeat all of step 3. |
| 463 | |
| 464 | |
| 465 | 7. Release the JPEG compression object. |
| 466 | |
| 467 | When you are done with a JPEG compression object, destroy it by calling |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 468 | jpeg_destroy_compress(). This will free all subsidiary memory (regardless of |
| 469 | the previous state of the object). Or you can call jpeg_destroy(), which |
| 470 | works for either compression or decompression objects --- this may be more |
| 471 | convenient if you are sharing code between compression and decompression |
| 472 | cases. (Actually, these routines are equivalent except for the declared type |
| 473 | of the passed pointer. To avoid gripes from ANSI C compilers, jpeg_destroy() |
| 474 | should be passed a j_common_ptr.) |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 475 | |
| 476 | If you allocated the jpeg_compress_struct structure from malloc(), freeing |
| 477 | it is your responsibility --- jpeg_destroy() won't. Ditto for the error |
| 478 | handler structure. |
| 479 | |
| 480 | Typical code: |
| 481 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 482 | jpeg_destroy_compress(&cinfo); |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 483 | |
| 484 | |
| 485 | 8. Aborting. |
| 486 | |
| 487 | If you decide to abort a compression cycle before finishing, you can clean up |
| 488 | in either of two ways: |
| 489 | |
| 490 | * If you don't need the JPEG object any more, just call |
| 491 | jpeg_destroy_compress() or jpeg_destroy() to release memory. This is |
| 492 | legitimate at any point after calling jpeg_create_compress() --- in fact, |
| 493 | it's safe even if jpeg_create_compress() fails. |
| 494 | |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 495 | * If you want to re-use the JPEG object, call jpeg_abort_compress(), or call |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 496 | jpeg_abort() which works on both compression and decompression objects. |
| 497 | This will return the object to an idle state, releasing any working memory. |
| 498 | jpeg_abort() is allowed at any time after successful object creation. |
| 499 | |
| 500 | Note that cleaning up the data destination, if required, is your |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 501 | responsibility; neither of these routines will call term_destination(). |
| 502 | (See "Compressed data handling", below, for more about that.) |
| 503 | |
| 504 | jpeg_destroy() and jpeg_abort() are the only safe calls to make on a JPEG |
| 505 | object that has reported an error by calling error_exit (see "Error handling" |
| 506 | for more info). The internal state of such an object is likely to be out of |
| 507 | whack. Either of these two routines will return the object to a known state. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 508 | |
| 509 | |
| 510 | Decompression details |
| 511 | --------------------- |
| 512 | |
| 513 | Here we revisit the JPEG decompression outline given in the overview. |
| 514 | |
| 515 | 1. Allocate and initialize a JPEG decompression object. |
| 516 | |
| 517 | This is just like initialization for compression, as discussed above, |
| 518 | except that the object is a "struct jpeg_decompress_struct" and you |
| 519 | call jpeg_create_decompress(). Error handling is exactly the same. |
| 520 | |
| 521 | Typical code: |
| 522 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 523 | struct jpeg_decompress_struct cinfo; |
| 524 | struct jpeg_error_mgr jerr; |
| 525 | ... |
| 526 | cinfo.err = jpeg_std_error(&jerr); |
| 527 | jpeg_create_decompress(&cinfo); |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 528 | |
| 529 | (Both here and in the IJG code, we usually use variable name "cinfo" for |
| 530 | both compression and decompression objects.) |
| 531 | |
| 532 | |
| 533 | 2. Specify the source of the compressed data (eg, a file). |
| 534 | |
| 535 | As previously mentioned, the JPEG library reads compressed data from a "data |
| 536 | source" module. The library includes one data source module which knows how |
| 537 | to read from a stdio stream. You can use your own source module if you want |
| 538 | to do something else, as discussed later. |
| 539 | |
| 540 | If you use the standard source module, you must open the source stdio stream |
| 541 | beforehand. Typical code for this step looks like: |
| 542 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 543 | FILE * infile; |
| 544 | ... |
| 545 | if ((infile = fopen(filename, "rb")) == NULL) { |
| 546 | fprintf(stderr, "can't open %s\n", filename); |
| 547 | exit(1); |
| 548 | } |
| 549 | jpeg_stdio_src(&cinfo, infile); |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 550 | |
| 551 | where the last line invokes the standard source module. |
| 552 | |
| 553 | WARNING: it is critical that the binary compressed data be read unchanged. |
| 554 | On non-Unix systems the stdio library may perform newline translation or |
| 555 | otherwise corrupt binary data. To suppress this behavior, you may need to use |
| 556 | a "b" option to fopen (as shown above), or use setmode() or another routine to |
| 557 | put the stdio stream in binary mode. See cjpeg.c and djpeg.c for code that |
| 558 | has been found to work on many systems. |
| 559 | |
| 560 | You may not change the data source between calling jpeg_read_header() and |
| 561 | jpeg_finish_decompress(). If you wish to read a series of JPEG images from |
| 562 | a single source file, you should repeat the jpeg_read_header() to |
| 563 | jpeg_finish_decompress() sequence without reinitializing either the JPEG |
| 564 | object or the data source module; this prevents buffered input data from |
| 565 | being discarded. |
| 566 | |
| 567 | |
| 568 | 3. Call jpeg_read_header() to obtain image info. |
| 569 | |
| 570 | Typical code for this step is just |
| 571 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 572 | jpeg_read_header(&cinfo, TRUE); |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 573 | |
| 574 | This will read the source datastream header markers, up to the beginning |
| 575 | of the compressed data proper. On return, the image dimensions and other |
| 576 | info have been stored in the JPEG object. The application may wish to |
| 577 | consult this information before selecting decompression parameters. |
| 578 | |
| 579 | More complex code is necessary if |
| 580 | * A suspending data source is used --- in that case jpeg_read_header() |
| 581 | may return before it has read all the header data. See "I/O suspension", |
| 582 | below. The normal stdio source manager will NOT cause this to happen. |
| 583 | * Abbreviated JPEG files are to be processed --- see the section on |
| 584 | abbreviated datastreams. Standard applications that deal only in |
| 585 | interchange JPEG files need not be concerned with this case either. |
| 586 | |
| 587 | It is permissible to stop at this point if you just wanted to find out the |
| 588 | image dimensions and other header info for a JPEG file. In that case, |
| 589 | call jpeg_destroy() when you are done with the JPEG object, or call |
| 590 | jpeg_abort() to return it to an idle state before selecting a new data |
| 591 | source and reading another header. |
| 592 | |
| 593 | |
| 594 | 4. Set parameters for decompression. |
| 595 | |
| 596 | jpeg_read_header() sets appropriate default decompression parameters based on |
| 597 | the properties of the image (in particular, its colorspace). However, you |
| 598 | may well want to alter these defaults before beginning the decompression. |
| 599 | For example, the default is to produce full color output from a color file. |
| 600 | If you want colormapped output you must ask for it. Other options allow the |
| 601 | returned image to be scaled and allow various speed/quality tradeoffs to be |
| 602 | selected. "Decompression parameter selection", below, gives details. |
| 603 | |
| 604 | If the defaults are appropriate, nothing need be done at this step. |
| 605 | |
| 606 | Note that all default values are set by each call to jpeg_read_header(). |
| 607 | If you reuse a decompression object, you cannot expect your parameter |
| 608 | settings to be preserved across cycles, as you can for compression. |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 609 | You must set desired parameter values each time. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 610 | |
| 611 | |
| 612 | 5. jpeg_start_decompress(...); |
| 613 | |
| 614 | Once the parameter values are satisfactory, call jpeg_start_decompress() to |
| 615 | begin decompression. This will initialize internal state, allocate working |
| 616 | memory, and prepare for returning data. |
| 617 | |
| 618 | Typical code is just |
| 619 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 620 | jpeg_start_decompress(&cinfo); |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 621 | |
| 622 | If you have requested a multi-pass operating mode, such as 2-pass color |
| 623 | quantization, jpeg_start_decompress() will do everything needed before data |
| 624 | output can begin. In this case jpeg_start_decompress() may take quite a while |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 625 | to complete. With a single-scan (non progressive) JPEG file and default |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 626 | decompression parameters, this will not happen; jpeg_start_decompress() will |
| 627 | return quickly. |
| 628 | |
| 629 | After this call, the final output image dimensions, including any requested |
| 630 | scaling, are available in the JPEG object; so is the selected colormap, if |
| 631 | colormapped output has been requested. Useful fields include |
| 632 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 633 | output_width image width and height, as scaled |
| 634 | output_height |
| 635 | out_color_components # of color components in out_color_space |
| 636 | output_components # of color components returned per pixel |
| 637 | colormap the selected colormap, if any |
| 638 | actual_number_of_colors number of entries in colormap |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 639 | |
| 640 | output_components is 1 (a colormap index) when quantizing colors; otherwise it |
| 641 | equals out_color_components. It is the number of JSAMPLE values that will be |
| 642 | emitted per pixel in the output arrays. |
| 643 | |
| 644 | Typically you will need to allocate data buffers to hold the incoming image. |
| 645 | You will need output_width * output_components JSAMPLEs per scanline in your |
| 646 | output buffer, and a total of output_height scanlines will be returned. |
| 647 | |
| 648 | Note: if you are using the JPEG library's internal memory manager to allocate |
| 649 | data buffers (as djpeg does), then the manager's protocol requires that you |
| 650 | request large buffers *before* calling jpeg_start_decompress(). This is a |
| 651 | little tricky since the output_XXX fields are not normally valid then. You |
| 652 | can make them valid by calling jpeg_calc_output_dimensions() after setting the |
| 653 | relevant parameters (scaling, output color space, and quantization flag). |
| 654 | |
| 655 | |
| 656 | 6. while (scan lines remain to be read) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 657 | jpeg_read_scanlines(...); |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 658 | |
| 659 | Now you can read the decompressed image data by calling jpeg_read_scanlines() |
| 660 | one or more times. At each call, you pass in the maximum number of scanlines |
| 661 | to be read (ie, the height of your working buffer); jpeg_read_scanlines() |
| 662 | will return up to that many lines. The return value is the number of lines |
| 663 | actually read. The format of the returned data is discussed under "Data |
Thomas G. Lane | a8b67c4 | 1995-03-15 00:00:00 +0000 | [diff] [blame] | 664 | formats", above. Don't forget that grayscale and color JPEGs will return |
| 665 | different data formats! |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 666 | |
| 667 | Image data is returned in top-to-bottom scanline order. If you must write |
| 668 | out the image in bottom-to-top order, you can use the JPEG library's virtual |
| 669 | array mechanism to invert the data efficiently. Examples of this can be |
| 670 | found in the sample application djpeg. |
| 671 | |
| 672 | The library maintains a count of the number of scanlines returned so far |
| 673 | in the output_scanline field of the JPEG object. Usually you can just use |
| 674 | this variable as the loop counter, so that the loop test looks like |
| 675 | "while (cinfo.output_scanline < cinfo.output_height)". (Note that the test |
| 676 | should NOT be against image_height, unless you never use scaling. The |
| 677 | image_height field is the height of the original unscaled image.) |
Thomas G. Lane | 9ba2f5e | 1994-12-07 00:00:00 +0000 | [diff] [blame] | 678 | The return value always equals the change in the value of output_scanline. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 679 | |
| 680 | If you don't use a suspending data source, it is safe to assume that |
| 681 | jpeg_read_scanlines() reads at least one scanline per call, until the |
Thomas G. Lane | 489583f | 1996-02-07 00:00:00 +0000 | [diff] [blame] | 682 | bottom of the image has been reached. |
| 683 | |
| 684 | If you use a buffer larger than one scanline, it is NOT safe to assume that |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 685 | jpeg_read_scanlines() fills it. (The current implementation returns only a |
| 686 | few scanlines per call, no matter how large a buffer you pass.) So you must |
| 687 | always provide a loop that calls jpeg_read_scanlines() repeatedly until the |
| 688 | whole image has been read. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 689 | |
| 690 | |
| 691 | 7. jpeg_finish_decompress(...); |
| 692 | |
| 693 | After all the image data has been read, call jpeg_finish_decompress() to |
| 694 | complete the decompression cycle. This causes working memory associated |
| 695 | with the JPEG object to be released. |
| 696 | |
| 697 | Typical code: |
| 698 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 699 | jpeg_finish_decompress(&cinfo); |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 700 | |
| 701 | If using the stdio source manager, don't forget to close the source stdio |
| 702 | stream if necessary. |
| 703 | |
| 704 | It is an error to call jpeg_finish_decompress() before reading the correct |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 705 | total number of scanlines. If you wish to abort decompression, call |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 706 | jpeg_abort() as discussed below. |
| 707 | |
| 708 | After completing a decompression cycle, you may dispose of the JPEG object as |
| 709 | discussed next, or you may use it to decompress another image. In that case |
| 710 | return to step 2 or 3 as appropriate. If you do not change the source |
| 711 | manager, the next image will be read from the same source. |
| 712 | |
| 713 | |
| 714 | 8. Release the JPEG decompression object. |
| 715 | |
| 716 | When you are done with a JPEG decompression object, destroy it by calling |
| 717 | jpeg_destroy_decompress() or jpeg_destroy(). The previous discussion of |
| 718 | destroying compression objects applies here too. |
| 719 | |
| 720 | Typical code: |
| 721 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 722 | jpeg_destroy_decompress(&cinfo); |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 723 | |
| 724 | |
| 725 | 9. Aborting. |
| 726 | |
| 727 | You can abort a decompression cycle by calling jpeg_destroy_decompress() or |
| 728 | jpeg_destroy() if you don't need the JPEG object any more, or |
| 729 | jpeg_abort_decompress() or jpeg_abort() if you want to reuse the object. |
| 730 | The previous discussion of aborting compression cycles applies here too. |
| 731 | |
| 732 | |
DRC | eb32cc1 | 2015-06-25 03:44:36 +0000 | [diff] [blame] | 733 | Skipping rows when decompressing |
| 734 | -------------------------------- |
| 735 | |
| 736 | jpeg_skip_scanlines(j_decompress_ptr cinfo, JDIMENSION num_lines); |
| 737 | |
| 738 | This function provides application programmers with the ability to skip over |
| 739 | multiple rows in the JPEG image, thus decoding only a subset of the image data. |
| 740 | This is convenient for performance-critical applications that wish to view only |
| 741 | a portion of a large JPEG image without decompressing the whole thing. It it |
| 742 | also useful in memory-constrained environments (such as on mobile devices.) |
| 743 | |
| 744 | Suspending data sources are not supported by this function. Calling |
| 745 | jpeg_skip_scanlines() with a suspending data source will result in undefined |
| 746 | behavior. |
| 747 | |
| 748 | jpeg_skip_scanlines() will not allow skipping past the bottom of the image. If |
| 749 | the value of num_lines is large enough to skip past the bottom of the image, |
| 750 | then the function will skip to the end of the image instead. |
| 751 | |
| 752 | If the value of num_lines is valid, then jpeg_skip_scanlines() will always |
| 753 | skip all of the input rows requested. There is no need to inspect the return |
| 754 | value of the function in that case. |
| 755 | |
| 756 | Best results will be achieved by calling jpeg_skip_scanlines() for large chunks |
| 757 | of rows. The function should be viewed as a way to quickly jump to a |
| 758 | particular vertical offset in the JPEG image in order to decode a subset of the |
| 759 | image. Used in this manner, it will provide significant performance |
| 760 | improvements. |
| 761 | |
| 762 | Calling jpeg_skip_scanlines() for small values of num_lines has several |
| 763 | potential drawbacks: |
| 764 | 1) JPEG decompression occurs in blocks, so if jpeg_skip_scanlines() is |
| 765 | called from the middle of a decompression block, then it is likely that |
| 766 | much of the decompression work has already been done for the first |
| 767 | couple of rows that need to be skipped. |
| 768 | 2) When this function returns, it must leave the decompressor in a state |
| 769 | such that it is ready to read the next line. This may involve |
| 770 | decompressing a block that must be partially skipped. |
| 771 | These issues are especially tricky for cases in which upsampling requires |
| 772 | context rows. In the worst case, jpeg_skip_scanlines() will perform similarly |
| 773 | to jpeg_read_scanlines() (since it will actually call jpeg_read_scanlines().) |
| 774 | |
| 775 | |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 776 | Mechanics of usage: include files, linking, etc |
| 777 | ----------------------------------------------- |
| 778 | |
| 779 | Applications using the JPEG library should include the header file jpeglib.h |
| 780 | to obtain declarations of data types and routines. Before including |
| 781 | jpeglib.h, include system headers that define at least the typedefs FILE and |
| 782 | size_t. On ANSI-conforming systems, including <stdio.h> is sufficient; on |
| 783 | older Unix systems, you may need <sys/types.h> to define size_t. |
| 784 | |
| 785 | If the application needs to refer to individual JPEG library error codes, also |
| 786 | include jerror.h to define those symbols. |
| 787 | |
| 788 | jpeglib.h indirectly includes the files jconfig.h and jmorecfg.h. If you are |
| 789 | installing the JPEG header files in a system directory, you will want to |
| 790 | install all four files: jpeglib.h, jerror.h, jconfig.h, jmorecfg.h. |
| 791 | |
| 792 | The most convenient way to include the JPEG code into your executable program |
| 793 | is to prepare a library file ("libjpeg.a", or a corresponding name on non-Unix |
| 794 | machines) and reference it at your link step. If you use only half of the |
| 795 | library (only compression or only decompression), only that much code will be |
| 796 | included from the library, unless your linker is hopelessly brain-damaged. |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 797 | The supplied makefiles build libjpeg.a automatically (see install.txt). |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 798 | |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 799 | While you can build the JPEG library as a shared library if the whim strikes |
| 800 | you, we don't really recommend it. The trouble with shared libraries is that |
| 801 | at some point you'll probably try to substitute a new version of the library |
| 802 | without recompiling the calling applications. That generally doesn't work |
| 803 | because the parameter struct declarations usually change with each new |
| 804 | version. In other words, the library's API is *not* guaranteed binary |
| 805 | compatible across versions; we only try to ensure source-code compatibility. |
| 806 | (In hindsight, it might have been smarter to hide the parameter structs from |
| 807 | applications and introduce a ton of access functions instead. Too late now, |
| 808 | however.) |
| 809 | |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 810 | It may be worth pointing out that the core JPEG library does not actually |
| 811 | require the stdio library: only the default source/destination managers and |
| 812 | error handler need it. You can use the library in a stdio-less environment |
| 813 | if you replace those modules and use jmemnobs.c (or another memory manager of |
| 814 | your own devising). More info about the minimum system library requirements |
| 815 | may be found in jinclude.h. |
| 816 | |
| 817 | |
| 818 | ADVANCED FEATURES |
| 819 | ================= |
| 820 | |
| 821 | Compression parameter selection |
| 822 | ------------------------------- |
| 823 | |
| 824 | This section describes all the optional parameters you can set for JPEG |
| 825 | compression, as well as the "helper" routines provided to assist in this |
| 826 | task. Proper setting of some parameters requires detailed understanding |
| 827 | of the JPEG standard; if you don't know what a parameter is for, it's best |
DRC | 7e3acc0 | 2015-10-10 10:25:46 -0500 | [diff] [blame] | 828 | not to mess with it! See REFERENCES in the README.ijg file for pointers to |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 829 | more info about JPEG. |
| 830 | |
| 831 | It's a good idea to call jpeg_set_defaults() first, even if you plan to set |
| 832 | all the parameters; that way your code is more likely to work with future JPEG |
| 833 | libraries that have additional parameters. For the same reason, we recommend |
| 834 | you use a helper routine where one is provided, in preference to twiddling |
| 835 | cinfo fields directly. |
| 836 | |
| 837 | The helper routines are: |
| 838 | |
| 839 | jpeg_set_defaults (j_compress_ptr cinfo) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 840 | This routine sets all JPEG parameters to reasonable defaults, using |
| 841 | only the input image's color space (field in_color_space, which must |
| 842 | already be set in cinfo). Many applications will only need to use |
| 843 | this routine and perhaps jpeg_set_quality(). |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 844 | |
| 845 | jpeg_set_colorspace (j_compress_ptr cinfo, J_COLOR_SPACE colorspace) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 846 | Sets the JPEG file's colorspace (field jpeg_color_space) as specified, |
| 847 | and sets other color-space-dependent parameters appropriately. See |
| 848 | "Special color spaces", below, before using this. A large number of |
| 849 | parameters, including all per-component parameters, are set by this |
| 850 | routine; if you want to twiddle individual parameters you should call |
| 851 | jpeg_set_colorspace() before rather than after. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 852 | |
| 853 | jpeg_default_colorspace (j_compress_ptr cinfo) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 854 | Selects an appropriate JPEG colorspace based on cinfo->in_color_space, |
| 855 | and calls jpeg_set_colorspace(). This is actually a subroutine of |
| 856 | jpeg_set_defaults(). It's broken out in case you want to change |
| 857 | just the colorspace-dependent JPEG parameters. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 858 | |
| 859 | jpeg_set_quality (j_compress_ptr cinfo, int quality, boolean force_baseline) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 860 | Constructs JPEG quantization tables appropriate for the indicated |
| 861 | quality setting. The quality value is expressed on the 0..100 scale |
| 862 | recommended by IJG (cjpeg's "-quality" switch uses this routine). |
| 863 | Note that the exact mapping from quality values to tables may change |
| 864 | in future IJG releases as more is learned about DCT quantization. |
| 865 | If the force_baseline parameter is TRUE, then the quantization table |
| 866 | entries are constrained to the range 1..255 for full JPEG baseline |
| 867 | compatibility. In the current implementation, this only makes a |
| 868 | difference for quality settings below 25, and it effectively prevents |
| 869 | very small/low quality files from being generated. The IJG decoder |
| 870 | is capable of reading the non-baseline files generated at low quality |
| 871 | settings when force_baseline is FALSE, but other decoders may not be. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 872 | |
| 873 | jpeg_set_linear_quality (j_compress_ptr cinfo, int scale_factor, |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 874 | boolean force_baseline) |
| 875 | Same as jpeg_set_quality() except that the generated tables are the |
| 876 | sample tables given in the JPEC spec section K.1, multiplied by the |
| 877 | specified scale factor (which is expressed as a percentage; thus |
| 878 | scale_factor = 100 reproduces the spec's tables). Note that larger |
| 879 | scale factors give lower quality. This entry point is useful for |
| 880 | conforming to the Adobe PostScript DCT conventions, but we do not |
| 881 | recommend linear scaling as a user-visible quality scale otherwise. |
| 882 | force_baseline again constrains the computed table entries to 1..255. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 883 | |
| 884 | int jpeg_quality_scaling (int quality) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 885 | Converts a value on the IJG-recommended quality scale to a linear |
| 886 | scaling percentage. Note that this routine may change or go away |
| 887 | in future releases --- IJG may choose to adopt a scaling method that |
| 888 | can't be expressed as a simple scalar multiplier, in which case the |
| 889 | premise of this routine collapses. Caveat user. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 890 | |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 891 | jpeg_default_qtables (j_compress_ptr cinfo, boolean force_baseline) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 892 | [libjpeg v7+ API/ABI emulation only] |
| 893 | Set default quantization tables with linear q_scale_factor[] values |
| 894 | (see below). |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 895 | |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 896 | jpeg_add_quant_table (j_compress_ptr cinfo, int which_tbl, |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 897 | const unsigned int *basic_table, |
| 898 | int scale_factor, boolean force_baseline) |
| 899 | Allows an arbitrary quantization table to be created. which_tbl |
| 900 | indicates which table slot to fill. basic_table points to an array |
| 901 | of 64 unsigned ints given in normal array order. These values are |
| 902 | multiplied by scale_factor/100 and then clamped to the range 1..65535 |
| 903 | (or to 1..255 if force_baseline is TRUE). |
| 904 | CAUTION: prior to library version 6a, jpeg_add_quant_table expected |
| 905 | the basic table to be given in JPEG zigzag order. If you need to |
| 906 | write code that works with either older or newer versions of this |
| 907 | routine, you must check the library version number. Something like |
| 908 | "#if JPEG_LIB_VERSION >= 61" is the right test. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 909 | |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 910 | jpeg_simple_progression (j_compress_ptr cinfo) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 911 | Generates a default scan script for writing a progressive-JPEG file. |
| 912 | This is the recommended method of creating a progressive file, |
| 913 | unless you want to make a custom scan sequence. You must ensure that |
| 914 | the JPEG color space is set correctly before calling this routine. |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 915 | |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 916 | |
| 917 | Compression parameters (cinfo fields) include: |
| 918 | |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 919 | J_DCT_METHOD dct_method |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 920 | Selects the algorithm used for the DCT step. Choices are: |
| 921 | JDCT_ISLOW: slow but accurate integer algorithm |
| 922 | JDCT_IFAST: faster, less accurate integer method |
| 923 | JDCT_FLOAT: floating-point method |
| 924 | JDCT_DEFAULT: default method (normally JDCT_ISLOW) |
| 925 | JDCT_FASTEST: fastest method (normally JDCT_IFAST) |
DRC | 8940e6c | 2014-05-11 09:46:28 +0000 | [diff] [blame] | 926 | In libjpeg-turbo, JDCT_IFAST is generally about 5-15% faster than |
| 927 | JDCT_ISLOW when using the x86/x86-64 SIMD extensions (results may vary |
| 928 | with other SIMD implementations, or when using libjpeg-turbo without |
| 929 | SIMD extensions.) For quality levels of 90 and below, there should be |
| 930 | little or no perceptible difference between the two algorithms. For |
| 931 | quality levels above 90, however, the difference between JDCT_IFAST and |
| 932 | JDCT_ISLOW becomes more pronounced. With quality=97, for instance, |
| 933 | JDCT_IFAST incurs generally about a 1-3 dB loss (in PSNR) relative to |
| 934 | JDCT_ISLOW, but this can be larger for some images. Do not use |
| 935 | JDCT_IFAST with quality levels above 97. The algorithm often |
| 936 | degenerates at quality=98 and above and can actually produce a more |
DRC | 05524e6 | 2014-05-11 23:14:43 +0000 | [diff] [blame] | 937 | lossy image than if lower quality levels had been used. Also, in |
| 938 | libjpeg-turbo, JDCT_IFAST is not fully accelerated for quality levels |
| 939 | above 97, so it will be slower than JDCT_ISLOW. JDCT_FLOAT is mainly a |
| 940 | legacy feature. It does not produce significantly more accurate |
| 941 | results than the ISLOW method, and it is much slower. The FLOAT method |
| 942 | may also give different results on different machines due to varying |
| 943 | roundoff behavior, whereas the integer methods should give the same |
| 944 | results on all machines. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 945 | |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 946 | J_COLOR_SPACE jpeg_color_space |
| 947 | int num_components |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 948 | The JPEG color space and corresponding number of components; see |
| 949 | "Special color spaces", below, for more info. We recommend using |
| 950 | jpeg_set_color_space() if you want to change these. |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 951 | |
| 952 | boolean optimize_coding |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 953 | TRUE causes the compressor to compute optimal Huffman coding tables |
| 954 | for the image. This requires an extra pass over the data and |
| 955 | therefore costs a good deal of space and time. The default is |
| 956 | FALSE, which tells the compressor to use the supplied or default |
| 957 | Huffman tables. In most cases optimal tables save only a few percent |
| 958 | of file size compared to the default tables. Note that when this is |
| 959 | TRUE, you need not supply Huffman tables at all, and any you do |
| 960 | supply will be overwritten. |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 961 | |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 962 | unsigned int restart_interval |
| 963 | int restart_in_rows |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 964 | To emit restart markers in the JPEG file, set one of these nonzero. |
| 965 | Set restart_interval to specify the exact interval in MCU blocks. |
| 966 | Set restart_in_rows to specify the interval in MCU rows. (If |
| 967 | restart_in_rows is not 0, then restart_interval is set after the |
| 968 | image width in MCUs is computed.) Defaults are zero (no restarts). |
| 969 | One restart marker per MCU row is often a good choice. |
| 970 | NOTE: the overhead of restart markers is higher in grayscale JPEG |
| 971 | files than in color files, and MUCH higher in progressive JPEGs. |
| 972 | If you use restarts, you may want to use larger intervals in those |
| 973 | cases. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 974 | |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 975 | const jpeg_scan_info * scan_info |
| 976 | int num_scans |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 977 | By default, scan_info is NULL; this causes the compressor to write a |
| 978 | single-scan sequential JPEG file. If not NULL, scan_info points to |
| 979 | an array of scan definition records of length num_scans. The |
| 980 | compressor will then write a JPEG file having one scan for each scan |
| 981 | definition record. This is used to generate noninterleaved or |
| 982 | progressive JPEG files. The library checks that the scan array |
| 983 | defines a valid JPEG scan sequence. (jpeg_simple_progression creates |
| 984 | a suitable scan definition array for progressive JPEG.) This is |
| 985 | discussed further under "Progressive JPEG support". |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 986 | |
| 987 | int smoothing_factor |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 988 | If non-zero, the input image is smoothed; the value should be 1 for |
| 989 | minimal smoothing to 100 for maximum smoothing. Consult jcsample.c |
| 990 | for details of the smoothing algorithm. The default is zero. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 991 | |
| 992 | boolean write_JFIF_header |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 993 | If TRUE, a JFIF APP0 marker is emitted. jpeg_set_defaults() and |
| 994 | jpeg_set_colorspace() set this TRUE if a JFIF-legal JPEG color space |
| 995 | (ie, YCbCr or grayscale) is selected, otherwise FALSE. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 996 | |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 997 | UINT8 JFIF_major_version |
| 998 | UINT8 JFIF_minor_version |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 999 | The version number to be written into the JFIF marker. |
| 1000 | jpeg_set_defaults() initializes the version to 1.01 (major=minor=1). |
| 1001 | You should set it to 1.02 (major=1, minor=2) if you plan to write |
| 1002 | any JFIF 1.02 extension markers. |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 1003 | |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1004 | UINT8 density_unit |
| 1005 | UINT16 X_density |
| 1006 | UINT16 Y_density |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1007 | The resolution information to be written into the JFIF marker; |
| 1008 | not used otherwise. density_unit may be 0 for unknown, |
| 1009 | 1 for dots/inch, or 2 for dots/cm. The default values are 0,1,1 |
| 1010 | indicating square pixels of unknown size. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1011 | |
| 1012 | boolean write_Adobe_marker |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1013 | If TRUE, an Adobe APP14 marker is emitted. jpeg_set_defaults() and |
| 1014 | jpeg_set_colorspace() set this TRUE if JPEG color space RGB, CMYK, |
| 1015 | or YCCK is selected, otherwise FALSE. It is generally a bad idea |
| 1016 | to set both write_JFIF_header and write_Adobe_marker. In fact, |
| 1017 | you probably shouldn't change the default settings at all --- the |
| 1018 | default behavior ensures that the JPEG file's color space can be |
| 1019 | recognized by the decoder. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1020 | |
| 1021 | JQUANT_TBL * quant_tbl_ptrs[NUM_QUANT_TBLS] |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1022 | Pointers to coefficient quantization tables, one per table slot, |
| 1023 | or NULL if no table is defined for a slot. Usually these should |
| 1024 | be set via one of the above helper routines; jpeg_add_quant_table() |
| 1025 | is general enough to define any quantization table. The other |
| 1026 | routines will set up table slot 0 for luminance quality and table |
| 1027 | slot 1 for chrominance. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1028 | |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 1029 | int q_scale_factor[NUM_QUANT_TBLS] |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1030 | [libjpeg v7+ API/ABI emulation only] |
| 1031 | Linear quantization scaling factors (0-100, default 100) |
| 1032 | for use with jpeg_default_qtables(). |
| 1033 | See rdswitch.c and cjpeg.c for an example of usage. |
| 1034 | Note that the q_scale_factor[] values use "linear" scales, so JPEG |
| 1035 | quality levels chosen by the user must be converted to these scales |
| 1036 | using jpeg_quality_scaling(). Here is an example that corresponds to |
| 1037 | cjpeg -quality 90,70: |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 1038 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1039 | jpeg_set_defaults(cinfo); |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 1040 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1041 | /* Set luminance quality 90. */ |
| 1042 | cinfo->q_scale_factor[0] = jpeg_quality_scaling(90); |
| 1043 | /* Set chrominance quality 70. */ |
| 1044 | cinfo->q_scale_factor[1] = jpeg_quality_scaling(70); |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 1045 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1046 | jpeg_default_qtables(cinfo, force_baseline); |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 1047 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1048 | CAUTION: Setting separate quality levels for chrominance and luminance |
| 1049 | is mainly only useful if chrominance subsampling is disabled. 2x2 |
| 1050 | chrominance subsampling (AKA "4:2:0") is the default, but you can |
| 1051 | explicitly disable subsampling as follows: |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 1052 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1053 | cinfo->comp_info[0].v_samp_factor = 1; |
| 1054 | cinfo->comp_info[0].h_samp_factor = 1; |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 1055 | |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1056 | JHUFF_TBL * dc_huff_tbl_ptrs[NUM_HUFF_TBLS] |
| 1057 | JHUFF_TBL * ac_huff_tbl_ptrs[NUM_HUFF_TBLS] |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1058 | Pointers to Huffman coding tables, one per table slot, or NULL if |
| 1059 | no table is defined for a slot. Slots 0 and 1 are filled with the |
| 1060 | JPEG sample tables by jpeg_set_defaults(). If you need to allocate |
| 1061 | more table structures, jpeg_alloc_huff_table() may be used. |
| 1062 | Note that optimal Huffman tables can be computed for an image |
| 1063 | by setting optimize_coding, as discussed above; there's seldom |
| 1064 | any need to mess with providing your own Huffman tables. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1065 | |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 1066 | |
DRC | 3091354 | 2012-01-27 09:53:33 +0000 | [diff] [blame] | 1067 | [libjpeg v7+ API/ABI emulation only] |
| 1068 | The actual dimensions of the JPEG image that will be written to the file are |
| 1069 | given by the following fields. These are computed from the input image |
| 1070 | dimensions and the compression parameters by jpeg_start_compress(). You can |
| 1071 | also call jpeg_calc_jpeg_dimensions() to obtain the values that will result |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 1072 | from the current parameter settings. This can be useful if you are trying |
| 1073 | to pick a scaling ratio that will get close to a desired target size. |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 1074 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1075 | JDIMENSION jpeg_width Actual dimensions of output image. |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 1076 | JDIMENSION jpeg_height |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1077 | |
| 1078 | |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1079 | Per-component parameters are stored in the struct cinfo.comp_info[i] for |
| 1080 | component number i. Note that components here refer to components of the |
| 1081 | JPEG color space, *not* the source image color space. A suitably large |
| 1082 | comp_info[] array is allocated by jpeg_set_defaults(); if you choose not |
| 1083 | to use that routine, it's up to you to allocate the array. |
| 1084 | |
| 1085 | int component_id |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1086 | The one-byte identifier code to be recorded in the JPEG file for |
| 1087 | this component. For the standard color spaces, we recommend you |
| 1088 | leave the default values alone. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1089 | |
| 1090 | int h_samp_factor |
| 1091 | int v_samp_factor |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1092 | Horizontal and vertical sampling factors for the component; must |
| 1093 | be 1..4 according to the JPEG standard. Note that larger sampling |
| 1094 | factors indicate a higher-resolution component; many people find |
| 1095 | this behavior quite unintuitive. The default values are 2,2 for |
| 1096 | luminance components and 1,1 for chrominance components, except |
| 1097 | for grayscale where 1,1 is used. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1098 | |
| 1099 | int quant_tbl_no |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1100 | Quantization table number for component. The default value is |
| 1101 | 0 for luminance components and 1 for chrominance components. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1102 | |
| 1103 | int dc_tbl_no |
| 1104 | int ac_tbl_no |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1105 | DC and AC entropy coding table numbers. The default values are |
| 1106 | 0 for luminance components and 1 for chrominance components. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1107 | |
| 1108 | int component_index |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1109 | Must equal the component's index in comp_info[]. (Beginning in |
| 1110 | release v6, the compressor library will fill this in automatically; |
| 1111 | you don't have to.) |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1112 | |
| 1113 | |
| 1114 | Decompression parameter selection |
| 1115 | --------------------------------- |
| 1116 | |
| 1117 | Decompression parameter selection is somewhat simpler than compression |
| 1118 | parameter selection, since all of the JPEG internal parameters are |
| 1119 | recorded in the source file and need not be supplied by the application. |
| 1120 | (Unless you are working with abbreviated files, in which case see |
| 1121 | "Abbreviated datastreams", below.) Decompression parameters control |
| 1122 | the postprocessing done on the image to deliver it in a format suitable |
| 1123 | for the application's use. Many of the parameters control speed/quality |
| 1124 | tradeoffs, in which faster decompression may be obtained at the price of |
| 1125 | a poorer-quality image. The defaults select the highest quality (slowest) |
| 1126 | processing. |
| 1127 | |
| 1128 | The following fields in the JPEG object are set by jpeg_read_header() and |
| 1129 | may be useful to the application in choosing decompression parameters: |
| 1130 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1131 | JDIMENSION image_width Width and height of image |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1132 | JDIMENSION image_height |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1133 | int num_components Number of color components |
| 1134 | J_COLOR_SPACE jpeg_color_space Colorspace of image |
| 1135 | boolean saw_JFIF_marker TRUE if a JFIF APP0 marker was seen |
| 1136 | UINT8 JFIF_major_version Version information from JFIF marker |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 1137 | UINT8 JFIF_minor_version |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1138 | UINT8 density_unit Resolution data from JFIF marker |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1139 | UINT16 X_density |
| 1140 | UINT16 Y_density |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1141 | boolean saw_Adobe_marker TRUE if an Adobe APP14 marker was seen |
| 1142 | UINT8 Adobe_transform Color transform code from Adobe marker |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1143 | |
| 1144 | The JPEG color space, unfortunately, is something of a guess since the JPEG |
| 1145 | standard proper does not provide a way to record it. In practice most files |
| 1146 | adhere to the JFIF or Adobe conventions, and the decoder will recognize these |
| 1147 | correctly. See "Special color spaces", below, for more info. |
| 1148 | |
| 1149 | |
| 1150 | The decompression parameters that determine the basic properties of the |
| 1151 | returned image are: |
| 1152 | |
| 1153 | J_COLOR_SPACE out_color_space |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1154 | Output color space. jpeg_read_header() sets an appropriate default |
| 1155 | based on jpeg_color_space; typically it will be RGB or grayscale. |
| 1156 | The application can change this field to request output in a different |
| 1157 | colorspace. For example, set it to JCS_GRAYSCALE to get grayscale |
| 1158 | output from a color file. (This is useful for previewing: grayscale |
| 1159 | output is faster than full color since the color components need not |
| 1160 | be processed.) Note that not all possible color space transforms are |
| 1161 | currently implemented; you may need to extend jdcolor.c if you want an |
| 1162 | unusual conversion. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1163 | |
| 1164 | unsigned int scale_num, scale_denom |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1165 | Scale the image by the fraction scale_num/scale_denom. Default is |
| 1166 | 1/1, or no scaling. Currently, the only supported scaling ratios |
| 1167 | are M/8 with all M from 1 to 16, or any reduced fraction thereof (such |
| 1168 | as 1/2, 3/4, etc.) (The library design allows for arbitrary |
| 1169 | scaling ratios but this is not likely to be implemented any time soon.) |
| 1170 | Smaller scaling ratios permit significantly faster decoding since |
| 1171 | fewer pixels need be processed and a simpler IDCT method can be used. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1172 | |
| 1173 | boolean quantize_colors |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1174 | If set TRUE, colormapped output will be delivered. Default is FALSE, |
| 1175 | meaning that full-color output will be delivered. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1176 | |
| 1177 | The next three parameters are relevant only if quantize_colors is TRUE. |
| 1178 | |
| 1179 | int desired_number_of_colors |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1180 | Maximum number of colors to use in generating a library-supplied color |
| 1181 | map (the actual number of colors is returned in a different field). |
| 1182 | Default 256. Ignored when the application supplies its own color map. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1183 | |
| 1184 | boolean two_pass_quantize |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1185 | If TRUE, an extra pass over the image is made to select a custom color |
| 1186 | map for the image. This usually looks a lot better than the one-size- |
| 1187 | fits-all colormap that is used otherwise. Default is TRUE. Ignored |
| 1188 | when the application supplies its own color map. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1189 | |
| 1190 | J_DITHER_MODE dither_mode |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1191 | Selects color dithering method. Supported values are: |
| 1192 | JDITHER_NONE no dithering: fast, very low quality |
| 1193 | JDITHER_ORDERED ordered dither: moderate speed and quality |
| 1194 | JDITHER_FS Floyd-Steinberg dither: slow, high quality |
| 1195 | Default is JDITHER_FS. (At present, ordered dither is implemented |
| 1196 | only in the single-pass, standard-colormap case. If you ask for |
| 1197 | ordered dither when two_pass_quantize is TRUE or when you supply |
| 1198 | an external color map, you'll get F-S dithering.) |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1199 | |
| 1200 | When quantize_colors is TRUE, the target color map is described by the next |
| 1201 | two fields. colormap is set to NULL by jpeg_read_header(). The application |
| 1202 | can supply a color map by setting colormap non-NULL and setting |
| 1203 | actual_number_of_colors to the map size. Otherwise, jpeg_start_decompress() |
| 1204 | selects a suitable color map and sets these two fields itself. |
| 1205 | [Implementation restriction: at present, an externally supplied colormap is |
| 1206 | only accepted for 3-component output color spaces.] |
| 1207 | |
| 1208 | JSAMPARRAY colormap |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1209 | The color map, represented as a 2-D pixel array of out_color_components |
| 1210 | rows and actual_number_of_colors columns. Ignored if not quantizing. |
| 1211 | CAUTION: if the JPEG library creates its own colormap, the storage |
| 1212 | pointed to by this field is released by jpeg_finish_decompress(). |
| 1213 | Copy the colormap somewhere else first, if you want to save it. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1214 | |
| 1215 | int actual_number_of_colors |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1216 | The number of colors in the color map. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1217 | |
| 1218 | Additional decompression parameters that the application may set include: |
| 1219 | |
| 1220 | J_DCT_METHOD dct_method |
DRC | 8940e6c | 2014-05-11 09:46:28 +0000 | [diff] [blame] | 1221 | Selects the algorithm used for the DCT step. Choices are: |
| 1222 | JDCT_ISLOW: slow but accurate integer algorithm |
| 1223 | JDCT_IFAST: faster, less accurate integer method |
| 1224 | JDCT_FLOAT: floating-point method |
| 1225 | JDCT_DEFAULT: default method (normally JDCT_ISLOW) |
| 1226 | JDCT_FASTEST: fastest method (normally JDCT_IFAST) |
| 1227 | In libjpeg-turbo, JDCT_IFAST is generally about 5-15% faster than |
| 1228 | JDCT_ISLOW when using the x86/x86-64 SIMD extensions (results may vary |
| 1229 | with other SIMD implementations, or when using libjpeg-turbo without |
| 1230 | SIMD extensions.) If the JPEG image was compressed using a quality |
| 1231 | level of 85 or below, then there should be little or no perceptible |
| 1232 | difference between the two algorithms. When decompressing images that |
| 1233 | were compressed using quality levels above 85, however, the difference |
| 1234 | between JDCT_IFAST and JDCT_ISLOW becomes more pronounced. With images |
| 1235 | compressed using quality=97, for instance, JDCT_IFAST incurs generally |
| 1236 | about a 4-6 dB loss (in PSNR) relative to JDCT_ISLOW, but this can be |
| 1237 | larger for some images. If you can avoid it, do not use JDCT_IFAST |
| 1238 | when decompressing images that were compressed using quality levels |
| 1239 | above 97. The algorithm often degenerates for such images and can |
| 1240 | actually produce a more lossy output image than if the JPEG image had |
DRC | 05524e6 | 2014-05-11 23:14:43 +0000 | [diff] [blame] | 1241 | been compressed using lower quality levels. JDCT_FLOAT is mainly a |
DRC | 8940e6c | 2014-05-11 09:46:28 +0000 | [diff] [blame] | 1242 | legacy feature. It does not produce significantly more accurate |
| 1243 | results than the ISLOW method, and it is much slower. The FLOAT method |
| 1244 | may also give different results on different machines due to varying |
| 1245 | roundoff behavior, whereas the integer methods should give the same |
| 1246 | results on all machines. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1247 | |
| 1248 | boolean do_fancy_upsampling |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1249 | If TRUE, do careful upsampling of chroma components. If FALSE, |
| 1250 | a faster but sloppier method is used. Default is TRUE. The visual |
| 1251 | impact of the sloppier method is often very small. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1252 | |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1253 | boolean do_block_smoothing |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1254 | If TRUE, interblock smoothing is applied in early stages of decoding |
| 1255 | progressive JPEG files; if FALSE, not. Default is TRUE. Early |
| 1256 | progression stages look "fuzzy" with smoothing, "blocky" without. |
| 1257 | In any case, block smoothing ceases to be applied after the first few |
| 1258 | AC coefficients are known to full accuracy, so it is relevant only |
| 1259 | when using buffered-image mode for progressive images. |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1260 | |
| 1261 | boolean enable_1pass_quant |
| 1262 | boolean enable_external_quant |
| 1263 | boolean enable_2pass_quant |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1264 | These are significant only in buffered-image mode, which is |
| 1265 | described in its own section below. |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1266 | |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1267 | |
| 1268 | The output image dimensions are given by the following fields. These are |
| 1269 | computed from the source image dimensions and the decompression parameters |
| 1270 | by jpeg_start_decompress(). You can also call jpeg_calc_output_dimensions() |
| 1271 | to obtain the values that will result from the current parameter settings. |
| 1272 | This can be useful if you are trying to pick a scaling ratio that will get |
| 1273 | close to a desired target size. It's also important if you are using the |
| 1274 | JPEG library's memory manager to allocate output buffer space, because you |
| 1275 | are supposed to request such buffers *before* jpeg_start_decompress(). |
| 1276 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1277 | JDIMENSION output_width Actual dimensions of output image. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1278 | JDIMENSION output_height |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1279 | int out_color_components Number of color components in out_color_space. |
| 1280 | int output_components Number of color components returned. |
| 1281 | int rec_outbuf_height Recommended height of scanline buffer. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1282 | |
| 1283 | When quantizing colors, output_components is 1, indicating a single color map |
| 1284 | index per pixel. Otherwise it equals out_color_components. The output arrays |
| 1285 | are required to be output_width * output_components JSAMPLEs wide. |
| 1286 | |
| 1287 | rec_outbuf_height is the recommended minimum height (in scanlines) of the |
| 1288 | buffer passed to jpeg_read_scanlines(). If the buffer is smaller, the |
| 1289 | library will still work, but time will be wasted due to unnecessary data |
| 1290 | copying. In high-quality modes, rec_outbuf_height is always 1, but some |
| 1291 | faster, lower-quality modes set it to larger values (typically 2 to 4). |
| 1292 | If you are going to ask for a high-speed processing mode, you may as well |
| 1293 | go to the trouble of honoring rec_outbuf_height so as to avoid data copying. |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 1294 | (An output buffer larger than rec_outbuf_height lines is OK, but won't |
| 1295 | provide any material speed improvement over that height.) |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1296 | |
| 1297 | |
| 1298 | Special color spaces |
| 1299 | -------------------- |
| 1300 | |
| 1301 | The JPEG standard itself is "color blind" and doesn't specify any particular |
| 1302 | color space. It is customary to convert color data to a luminance/chrominance |
| 1303 | color space before compressing, since this permits greater compression. The |
| 1304 | existing de-facto JPEG file format standards specify YCbCr or grayscale data |
| 1305 | (JFIF), or grayscale, RGB, YCbCr, CMYK, or YCCK (Adobe). For special |
| 1306 | applications such as multispectral images, other color spaces can be used, |
| 1307 | but it must be understood that such files will be unportable. |
| 1308 | |
| 1309 | The JPEG library can handle the most common colorspace conversions (namely |
| 1310 | RGB <=> YCbCr and CMYK <=> YCCK). It can also deal with data of an unknown |
| 1311 | color space, passing it through without conversion. If you deal extensively |
| 1312 | with an unusual color space, you can easily extend the library to understand |
| 1313 | additional color spaces and perform appropriate conversions. |
| 1314 | |
| 1315 | For compression, the source data's color space is specified by field |
| 1316 | in_color_space. This is transformed to the JPEG file's color space given |
| 1317 | by jpeg_color_space. jpeg_set_defaults() chooses a reasonable JPEG color |
| 1318 | space depending on in_color_space, but you can override this by calling |
| 1319 | jpeg_set_colorspace(). Of course you must select a supported transformation. |
| 1320 | jccolor.c currently supports the following transformations: |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1321 | RGB => YCbCr |
| 1322 | RGB => GRAYSCALE |
| 1323 | YCbCr => GRAYSCALE |
| 1324 | CMYK => YCCK |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1325 | plus the null transforms: GRAYSCALE => GRAYSCALE, RGB => RGB, |
| 1326 | YCbCr => YCbCr, CMYK => CMYK, YCCK => YCCK, and UNKNOWN => UNKNOWN. |
| 1327 | |
| 1328 | The de-facto file format standards (JFIF and Adobe) specify APPn markers that |
| 1329 | indicate the color space of the JPEG file. It is important to ensure that |
| 1330 | these are written correctly, or omitted if the JPEG file's color space is not |
| 1331 | one of the ones supported by the de-facto standards. jpeg_set_colorspace() |
| 1332 | will set the compression parameters to include or omit the APPn markers |
| 1333 | properly, so long as it is told the truth about the JPEG color space. |
| 1334 | For example, if you are writing some random 3-component color space without |
| 1335 | conversion, don't try to fake out the library by setting in_color_space and |
| 1336 | jpeg_color_space to JCS_YCbCr; use JCS_UNKNOWN. You may want to write an |
| 1337 | APPn marker of your own devising to identify the colorspace --- see "Special |
| 1338 | markers", below. |
| 1339 | |
| 1340 | When told that the color space is UNKNOWN, the library will default to using |
| 1341 | luminance-quality compression parameters for all color components. You may |
| 1342 | well want to change these parameters. See the source code for |
| 1343 | jpeg_set_colorspace(), in jcparam.c, for details. |
| 1344 | |
| 1345 | For decompression, the JPEG file's color space is given in jpeg_color_space, |
| 1346 | and this is transformed to the output color space out_color_space. |
| 1347 | jpeg_read_header's setting of jpeg_color_space can be relied on if the file |
| 1348 | conforms to JFIF or Adobe conventions, but otherwise it is no better than a |
| 1349 | guess. If you know the JPEG file's color space for certain, you can override |
| 1350 | jpeg_read_header's guess by setting jpeg_color_space. jpeg_read_header also |
| 1351 | selects a default output color space based on (its guess of) jpeg_color_space; |
| 1352 | set out_color_space to override this. Again, you must select a supported |
| 1353 | transformation. jdcolor.c currently supports |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1354 | YCbCr => RGB |
| 1355 | YCbCr => GRAYSCALE |
| 1356 | RGB => GRAYSCALE |
| 1357 | GRAYSCALE => RGB |
| 1358 | YCCK => CMYK |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 1359 | as well as the null transforms. (Since GRAYSCALE=>RGB is provided, an |
| 1360 | application can force grayscale JPEGs to look like color JPEGs if it only |
| 1361 | wants to handle one case.) |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1362 | |
| 1363 | The two-pass color quantizer, jquant2.c, is specialized to handle RGB data |
| 1364 | (it weights distances appropriately for RGB colors). You'll need to modify |
| 1365 | the code if you want to use it for non-RGB output color spaces. Note that |
| 1366 | jquant2.c is used to map to an application-supplied colormap as well as for |
| 1367 | the normal two-pass colormap selection process. |
| 1368 | |
| 1369 | CAUTION: it appears that Adobe Photoshop writes inverted data in CMYK JPEG |
| 1370 | files: 0 represents 100% ink coverage, rather than 0% ink as you'd expect. |
| 1371 | This is arguably a bug in Photoshop, but if you need to work with Photoshop |
| 1372 | CMYK files, you will have to deal with it in your application. We cannot |
| 1373 | "fix" this in the library by inverting the data during the CMYK<=>YCCK |
| 1374 | transform, because that would break other applications, notably Ghostscript. |
| 1375 | Photoshop versions prior to 3.0 write EPS files containing JPEG-encoded CMYK |
| 1376 | data in the same inverted-YCCK representation used in bare JPEG files, but |
| 1377 | the surrounding PostScript code performs an inversion using the PS image |
| 1378 | operator. I am told that Photoshop 3.0 will write uninverted YCCK in |
| 1379 | EPS/JPEG files, and will omit the PS-level inversion. (But the data |
| 1380 | polarity used in bare JPEG files will not change in 3.0.) In either case, |
| 1381 | the JPEG library must not invert the data itself, or else Ghostscript would |
| 1382 | read these EPS files incorrectly. |
| 1383 | |
| 1384 | |
| 1385 | Error handling |
| 1386 | -------------- |
| 1387 | |
| 1388 | When the default error handler is used, any error detected inside the JPEG |
| 1389 | routines will cause a message to be printed on stderr, followed by exit(). |
| 1390 | You can supply your own error handling routines to override this behavior |
| 1391 | and to control the treatment of nonfatal warnings and trace/debug messages. |
| 1392 | The file example.c illustrates the most common case, which is to have the |
| 1393 | application regain control after an error rather than exiting. |
| 1394 | |
| 1395 | The JPEG library never writes any message directly; it always goes through |
| 1396 | the error handling routines. Three classes of messages are recognized: |
| 1397 | * Fatal errors: the library cannot continue. |
| 1398 | * Warnings: the library can continue, but the data is corrupt, and a |
| 1399 | damaged output image is likely to result. |
| 1400 | * Trace/informational messages. These come with a trace level indicating |
| 1401 | the importance of the message; you can control the verbosity of the |
| 1402 | program by adjusting the maximum trace level that will be displayed. |
| 1403 | |
| 1404 | You may, if you wish, simply replace the entire JPEG error handling module |
| 1405 | (jerror.c) with your own code. However, you can avoid code duplication by |
| 1406 | only replacing some of the routines depending on the behavior you need. |
| 1407 | This is accomplished by calling jpeg_std_error() as usual, but then overriding |
| 1408 | some of the method pointers in the jpeg_error_mgr struct, as illustrated by |
| 1409 | example.c. |
| 1410 | |
| 1411 | All of the error handling routines will receive a pointer to the JPEG object |
| 1412 | (a j_common_ptr which points to either a jpeg_compress_struct or a |
| 1413 | jpeg_decompress_struct; if you need to tell which, test the is_decompressor |
| 1414 | field). This struct includes a pointer to the error manager struct in its |
| 1415 | "err" field. Frequently, custom error handler routines will need to access |
| 1416 | additional data which is not known to the JPEG library or the standard error |
| 1417 | handler. The most convenient way to do this is to embed either the JPEG |
| 1418 | object or the jpeg_error_mgr struct in a larger structure that contains |
| 1419 | additional fields; then casting the passed pointer provides access to the |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 1420 | additional fields. Again, see example.c for one way to do it. (Beginning |
| 1421 | with IJG version 6b, there is also a void pointer "client_data" in each |
| 1422 | JPEG object, which the application can also use to find related data. |
| 1423 | The library does not touch client_data at all.) |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1424 | |
| 1425 | The individual methods that you might wish to override are: |
| 1426 | |
| 1427 | error_exit (j_common_ptr cinfo) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1428 | Receives control for a fatal error. Information sufficient to |
| 1429 | generate the error message has been stored in cinfo->err; call |
| 1430 | output_message to display it. Control must NOT return to the caller; |
| 1431 | generally this routine will exit() or longjmp() somewhere. |
| 1432 | Typically you would override this routine to get rid of the exit() |
| 1433 | default behavior. Note that if you continue processing, you should |
| 1434 | clean up the JPEG object with jpeg_abort() or jpeg_destroy(). |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1435 | |
| 1436 | output_message (j_common_ptr cinfo) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1437 | Actual output of any JPEG message. Override this to send messages |
| 1438 | somewhere other than stderr. Note that this method does not know |
| 1439 | how to generate a message, only where to send it. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1440 | |
| 1441 | format_message (j_common_ptr cinfo, char * buffer) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1442 | Constructs a readable error message string based on the error info |
| 1443 | stored in cinfo->err. This method is called by output_message. Few |
| 1444 | applications should need to override this method. One possible |
| 1445 | reason for doing so is to implement dynamic switching of error message |
| 1446 | language. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1447 | |
| 1448 | emit_message (j_common_ptr cinfo, int msg_level) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1449 | Decide whether or not to emit a warning or trace message; if so, |
| 1450 | calls output_message. The main reason for overriding this method |
| 1451 | would be to abort on warnings. msg_level is -1 for warnings, |
| 1452 | 0 and up for trace messages. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1453 | |
| 1454 | Only error_exit() and emit_message() are called from the rest of the JPEG |
| 1455 | library; the other two are internal to the error handler. |
| 1456 | |
| 1457 | The actual message texts are stored in an array of strings which is pointed to |
| 1458 | by the field err->jpeg_message_table. The messages are numbered from 0 to |
| 1459 | err->last_jpeg_message, and it is these code numbers that are used in the |
| 1460 | JPEG library code. You could replace the message texts (for instance, with |
| 1461 | messages in French or German) by changing the message table pointer. See |
| 1462 | jerror.h for the default texts. CAUTION: this table will almost certainly |
| 1463 | change or grow from one library version to the next. |
| 1464 | |
| 1465 | It may be useful for an application to add its own message texts that are |
| 1466 | handled by the same mechanism. The error handler supports a second "add-on" |
| 1467 | message table for this purpose. To define an addon table, set the pointer |
| 1468 | err->addon_message_table and the message numbers err->first_addon_message and |
| 1469 | err->last_addon_message. If you number the addon messages beginning at 1000 |
| 1470 | or so, you won't have to worry about conflicts with the library's built-in |
| 1471 | messages. See the sample applications cjpeg/djpeg for an example of using |
| 1472 | addon messages (the addon messages are defined in cderror.h). |
| 1473 | |
| 1474 | Actual invocation of the error handler is done via macros defined in jerror.h: |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1475 | ERREXITn(...) for fatal errors |
| 1476 | WARNMSn(...) for corrupt-data warnings |
| 1477 | TRACEMSn(...) for trace and informational messages. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1478 | These macros store the message code and any additional parameters into the |
| 1479 | error handler struct, then invoke the error_exit() or emit_message() method. |
| 1480 | The variants of each macro are for varying numbers of additional parameters. |
| 1481 | The additional parameters are inserted into the generated message using |
| 1482 | standard printf() format codes. |
| 1483 | |
| 1484 | See jerror.h and jerror.c for further details. |
| 1485 | |
| 1486 | |
| 1487 | Compressed data handling (source and destination managers) |
| 1488 | ---------------------------------------------------------- |
| 1489 | |
| 1490 | The JPEG compression library sends its compressed data to a "destination |
| 1491 | manager" module. The default destination manager just writes the data to a |
Guido Vollbeding | 989630f | 2010-01-10 00:00:00 +0000 | [diff] [blame] | 1492 | memory buffer or to a stdio stream, but you can provide your own manager to |
| 1493 | do something else. Similarly, the decompression library calls a "source |
| 1494 | manager" to obtain the compressed data; you can provide your own source |
| 1495 | manager if you want the data to come from somewhere other than a memory |
| 1496 | buffer or a stdio stream. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1497 | |
| 1498 | In both cases, compressed data is processed a bufferload at a time: the |
| 1499 | destination or source manager provides a work buffer, and the library invokes |
| 1500 | the manager only when the buffer is filled or emptied. (You could define a |
| 1501 | one-character buffer to force the manager to be invoked for each byte, but |
| 1502 | that would be rather inefficient.) The buffer's size and location are |
Guido Vollbeding | 989630f | 2010-01-10 00:00:00 +0000 | [diff] [blame] | 1503 | controlled by the manager, not by the library. For example, the memory |
| 1504 | source manager just makes the buffer pointer and length point to the original |
| 1505 | data in memory. In this case the buffer-reload procedure will be invoked |
| 1506 | only if the decompressor ran off the end of the datastream, which would |
| 1507 | indicate an erroneous datastream. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1508 | |
| 1509 | The work buffer is defined as an array of datatype JOCTET, which is generally |
| 1510 | "char" or "unsigned char". On a machine where char is not exactly 8 bits |
| 1511 | wide, you must define JOCTET as a wider data type and then modify the data |
| 1512 | source and destination modules to transcribe the work arrays into 8-bit units |
| 1513 | on external storage. |
| 1514 | |
| 1515 | A data destination manager struct contains a pointer and count defining the |
| 1516 | next byte to write in the work buffer and the remaining free space: |
| 1517 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1518 | JOCTET * next_output_byte; /* => next byte to write in buffer */ |
| 1519 | size_t free_in_buffer; /* # of byte spaces remaining in buffer */ |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1520 | |
| 1521 | The library increments the pointer and decrements the count until the buffer |
| 1522 | is filled. The manager's empty_output_buffer method must reset the pointer |
| 1523 | and count. The manager is expected to remember the buffer's starting address |
| 1524 | and total size in private fields not visible to the library. |
| 1525 | |
| 1526 | A data destination manager provides three methods: |
| 1527 | |
| 1528 | init_destination (j_compress_ptr cinfo) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1529 | Initialize destination. This is called by jpeg_start_compress() |
| 1530 | before any data is actually written. It must initialize |
| 1531 | next_output_byte and free_in_buffer. free_in_buffer must be |
| 1532 | initialized to a positive value. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1533 | |
| 1534 | empty_output_buffer (j_compress_ptr cinfo) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1535 | This is called whenever the buffer has filled (free_in_buffer |
| 1536 | reaches zero). In typical applications, it should write out the |
| 1537 | *entire* buffer (use the saved start address and buffer length; |
| 1538 | ignore the current state of next_output_byte and free_in_buffer). |
| 1539 | Then reset the pointer & count to the start of the buffer, and |
| 1540 | return TRUE indicating that the buffer has been dumped. |
| 1541 | free_in_buffer must be set to a positive value when TRUE is |
| 1542 | returned. A FALSE return should only be used when I/O suspension is |
| 1543 | desired (this operating mode is discussed in the next section). |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1544 | |
| 1545 | term_destination (j_compress_ptr cinfo) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1546 | Terminate destination --- called by jpeg_finish_compress() after all |
| 1547 | data has been written. In most applications, this must flush any |
| 1548 | data remaining in the buffer. Use either next_output_byte or |
| 1549 | free_in_buffer to determine how much data is in the buffer. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1550 | |
| 1551 | term_destination() is NOT called by jpeg_abort() or jpeg_destroy(). If you |
| 1552 | want the destination manager to be cleaned up during an abort, you must do it |
| 1553 | yourself. |
| 1554 | |
| 1555 | You will also need code to create a jpeg_destination_mgr struct, fill in its |
| 1556 | method pointers, and insert a pointer to the struct into the "dest" field of |
| 1557 | the JPEG compression object. This can be done in-line in your setup code if |
| 1558 | you like, but it's probably cleaner to provide a separate routine similar to |
Guido Vollbeding | 989630f | 2010-01-10 00:00:00 +0000 | [diff] [blame] | 1559 | the jpeg_stdio_dest() or jpeg_mem_dest() routines of the supplied destination |
| 1560 | managers. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1561 | |
| 1562 | Decompression source managers follow a parallel design, but with some |
| 1563 | additional frammishes. The source manager struct contains a pointer and count |
| 1564 | defining the next byte to read from the work buffer and the number of bytes |
| 1565 | remaining: |
| 1566 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1567 | const JOCTET * next_input_byte; /* => next byte to read from buffer */ |
| 1568 | size_t bytes_in_buffer; /* # of bytes remaining in buffer */ |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1569 | |
| 1570 | The library increments the pointer and decrements the count until the buffer |
| 1571 | is emptied. The manager's fill_input_buffer method must reset the pointer and |
| 1572 | count. In most applications, the manager must remember the buffer's starting |
| 1573 | address and total size in private fields not visible to the library. |
| 1574 | |
| 1575 | A data source manager provides five methods: |
| 1576 | |
| 1577 | init_source (j_decompress_ptr cinfo) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1578 | Initialize source. This is called by jpeg_read_header() before any |
| 1579 | data is actually read. Unlike init_destination(), it may leave |
| 1580 | bytes_in_buffer set to 0 (in which case a fill_input_buffer() call |
| 1581 | will occur immediately). |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1582 | |
| 1583 | fill_input_buffer (j_decompress_ptr cinfo) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1584 | This is called whenever bytes_in_buffer has reached zero and more |
| 1585 | data is wanted. In typical applications, it should read fresh data |
| 1586 | into the buffer (ignoring the current state of next_input_byte and |
| 1587 | bytes_in_buffer), reset the pointer & count to the start of the |
| 1588 | buffer, and return TRUE indicating that the buffer has been reloaded. |
| 1589 | It is not necessary to fill the buffer entirely, only to obtain at |
| 1590 | least one more byte. bytes_in_buffer MUST be set to a positive value |
| 1591 | if TRUE is returned. A FALSE return should only be used when I/O |
| 1592 | suspension is desired (this mode is discussed in the next section). |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1593 | |
| 1594 | skip_input_data (j_decompress_ptr cinfo, long num_bytes) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1595 | Skip num_bytes worth of data. The buffer pointer and count should |
| 1596 | be advanced over num_bytes input bytes, refilling the buffer as |
| 1597 | needed. This is used to skip over a potentially large amount of |
| 1598 | uninteresting data (such as an APPn marker). In some applications |
| 1599 | it may be possible to optimize away the reading of the skipped data, |
| 1600 | but it's not clear that being smart is worth much trouble; large |
| 1601 | skips are uncommon. bytes_in_buffer may be zero on return. |
| 1602 | A zero or negative skip count should be treated as a no-op. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1603 | |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1604 | resync_to_restart (j_decompress_ptr cinfo, int desired) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1605 | This routine is called only when the decompressor has failed to find |
| 1606 | a restart (RSTn) marker where one is expected. Its mission is to |
| 1607 | find a suitable point for resuming decompression. For most |
| 1608 | applications, we recommend that you just use the default resync |
| 1609 | procedure, jpeg_resync_to_restart(). However, if you are able to back |
| 1610 | up in the input data stream, or if you have a-priori knowledge about |
| 1611 | the likely location of restart markers, you may be able to do better. |
| 1612 | Read the read_restart_marker() and jpeg_resync_to_restart() routines |
| 1613 | in jdmarker.c if you think you'd like to implement your own resync |
| 1614 | procedure. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1615 | |
| 1616 | term_source (j_decompress_ptr cinfo) |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1617 | Terminate source --- called by jpeg_finish_decompress() after all |
| 1618 | data has been read. Often a no-op. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1619 | |
| 1620 | For both fill_input_buffer() and skip_input_data(), there is no such thing |
| 1621 | as an EOF return. If the end of the file has been reached, the routine has |
| 1622 | a choice of exiting via ERREXIT() or inserting fake data into the buffer. |
| 1623 | In most cases, generating a warning message and inserting a fake EOI marker |
| 1624 | is the best course of action --- this will allow the decompressor to output |
| 1625 | however much of the image is there. In pathological cases, the decompressor |
| 1626 | may swallow the EOI and again demand data ... just keep feeding it fake EOIs. |
| 1627 | jdatasrc.c illustrates the recommended error recovery behavior. |
| 1628 | |
| 1629 | term_source() is NOT called by jpeg_abort() or jpeg_destroy(). If you want |
| 1630 | the source manager to be cleaned up during an abort, you must do it yourself. |
| 1631 | |
| 1632 | You will also need code to create a jpeg_source_mgr struct, fill in its method |
| 1633 | pointers, and insert a pointer to the struct into the "src" field of the JPEG |
| 1634 | decompression object. This can be done in-line in your setup code if you |
| 1635 | like, but it's probably cleaner to provide a separate routine similar to the |
Guido Vollbeding | 989630f | 2010-01-10 00:00:00 +0000 | [diff] [blame] | 1636 | jpeg_stdio_src() or jpeg_mem_src() routines of the supplied source managers. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1637 | |
Guido Vollbeding | 989630f | 2010-01-10 00:00:00 +0000 | [diff] [blame] | 1638 | For more information, consult the memory and stdio source and destination |
| 1639 | managers in jdatasrc.c and jdatadst.c. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1640 | |
| 1641 | |
| 1642 | I/O suspension |
| 1643 | -------------- |
| 1644 | |
| 1645 | Some applications need to use the JPEG library as an incremental memory-to- |
| 1646 | memory filter: when the compressed data buffer is filled or emptied, they want |
| 1647 | control to return to the outer loop, rather than expecting that the buffer can |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1648 | be emptied or reloaded within the data source/destination manager subroutine. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1649 | The library supports this need by providing an "I/O suspension" mode, which we |
| 1650 | describe in this section. |
| 1651 | |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1652 | The I/O suspension mode is not a panacea: nothing is guaranteed about the |
| 1653 | maximum amount of time spent in any one call to the library, so it will not |
| 1654 | eliminate response-time problems in single-threaded applications. If you |
| 1655 | need guaranteed response time, we suggest you "bite the bullet" and implement |
| 1656 | a real multi-tasking capability. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1657 | |
| 1658 | To use I/O suspension, cooperation is needed between the calling application |
| 1659 | and the data source or destination manager; you will always need a custom |
| 1660 | source/destination manager. (Please read the previous section if you haven't |
| 1661 | already.) The basic idea is that the empty_output_buffer() or |
| 1662 | fill_input_buffer() routine is a no-op, merely returning FALSE to indicate |
| 1663 | that it has done nothing. Upon seeing this, the JPEG library suspends |
| 1664 | operation and returns to its caller. The surrounding application is |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1665 | responsible for emptying or refilling the work buffer before calling the |
| 1666 | JPEG library again. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1667 | |
| 1668 | Compression suspension: |
| 1669 | |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1670 | For compression suspension, use an empty_output_buffer() routine that returns |
| 1671 | FALSE; typically it will not do anything else. This will cause the |
| 1672 | compressor to return to the caller of jpeg_write_scanlines(), with the return |
| 1673 | value indicating that not all the supplied scanlines have been accepted. |
| 1674 | The application must make more room in the output buffer, adjust the output |
| 1675 | buffer pointer/count appropriately, and then call jpeg_write_scanlines() |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1676 | again, pointing to the first unconsumed scanline. |
| 1677 | |
| 1678 | When forced to suspend, the compressor will backtrack to a convenient stopping |
| 1679 | point (usually the start of the current MCU); it will regenerate some output |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1680 | data when restarted. Therefore, although empty_output_buffer() is only |
| 1681 | called when the buffer is filled, you should NOT write out the entire buffer |
| 1682 | after a suspension. Write only the data up to the current position of |
| 1683 | next_output_byte/free_in_buffer. The data beyond that point will be |
| 1684 | regenerated after resumption. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1685 | |
| 1686 | Because of the backtracking behavior, a good-size output buffer is essential |
| 1687 | for efficiency; you don't want the compressor to suspend often. (In fact, an |
| 1688 | overly small buffer could lead to infinite looping, if a single MCU required |
| 1689 | more data than would fit in the buffer.) We recommend a buffer of at least |
| 1690 | several Kbytes. You may want to insert explicit code to ensure that you don't |
| 1691 | call jpeg_write_scanlines() unless there is a reasonable amount of space in |
| 1692 | the output buffer; in other words, flush the buffer before trying to compress |
| 1693 | more data. |
| 1694 | |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1695 | The compressor does not allow suspension while it is trying to write JPEG |
| 1696 | markers at the beginning and end of the file. This means that: |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1697 | * At the beginning of a compression operation, there must be enough free |
| 1698 | space in the output buffer to hold the header markers (typically 600 or |
| 1699 | so bytes). The recommended buffer size is bigger than this anyway, so |
| 1700 | this is not a problem as long as you start with an empty buffer. However, |
| 1701 | this restriction might catch you if you insert large special markers, such |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1702 | as a JFIF thumbnail image, without flushing the buffer afterwards. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1703 | * When you call jpeg_finish_compress(), there must be enough space in the |
| 1704 | output buffer to emit any buffered data and the final EOI marker. In the |
| 1705 | current implementation, half a dozen bytes should suffice for this, but |
| 1706 | for safety's sake we recommend ensuring that at least 100 bytes are free |
| 1707 | before calling jpeg_finish_compress(). |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1708 | |
| 1709 | A more significant restriction is that jpeg_finish_compress() cannot suspend. |
| 1710 | This means you cannot use suspension with multi-pass operating modes, namely |
| 1711 | Huffman code optimization and multiple-scan output. Those modes write the |
| 1712 | whole file during jpeg_finish_compress(), which will certainly result in |
| 1713 | buffer overrun. (Note that this restriction applies only to compression, |
| 1714 | not decompression. The decompressor supports input suspension in all of its |
| 1715 | operating modes.) |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1716 | |
| 1717 | Decompression suspension: |
| 1718 | |
| 1719 | For decompression suspension, use a fill_input_buffer() routine that simply |
| 1720 | returns FALSE (except perhaps during error recovery, as discussed below). |
| 1721 | This will cause the decompressor to return to its caller with an indication |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1722 | that suspension has occurred. This can happen at four places: |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1723 | * jpeg_read_header(): will return JPEG_SUSPENDED. |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1724 | * jpeg_start_decompress(): will return FALSE, rather than its usual TRUE. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1725 | * jpeg_read_scanlines(): will return the number of scanlines already |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1726 | completed (possibly 0). |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1727 | * jpeg_finish_decompress(): will return FALSE, rather than its usual TRUE. |
| 1728 | The surrounding application must recognize these cases, load more data into |
| 1729 | the input buffer, and repeat the call. In the case of jpeg_read_scanlines(), |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1730 | increment the passed pointers past any scanlines successfully read. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1731 | |
| 1732 | Just as with compression, the decompressor will typically backtrack to a |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1733 | convenient restart point before suspending. When fill_input_buffer() is |
| 1734 | called, next_input_byte/bytes_in_buffer point to the current restart point, |
| 1735 | which is where the decompressor will backtrack to if FALSE is returned. |
| 1736 | The data beyond that position must NOT be discarded if you suspend; it needs |
| 1737 | to be re-read upon resumption. In most implementations, you'll need to shift |
| 1738 | this data down to the start of your work buffer and then load more data after |
| 1739 | it. Again, this behavior means that a several-Kbyte work buffer is essential |
| 1740 | for decent performance; furthermore, you should load a reasonable amount of |
| 1741 | new data before resuming decompression. (If you loaded, say, only one new |
| 1742 | byte each time around, you could waste a LOT of cycles.) |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1743 | |
| 1744 | The skip_input_data() source manager routine requires special care in a |
| 1745 | suspension scenario. This routine is NOT granted the ability to suspend the |
| 1746 | decompressor; it can decrement bytes_in_buffer to zero, but no more. If the |
| 1747 | requested skip distance exceeds the amount of data currently in the input |
| 1748 | buffer, then skip_input_data() must set bytes_in_buffer to zero and record the |
| 1749 | additional skip distance somewhere else. The decompressor will immediately |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1750 | call fill_input_buffer(), which should return FALSE, which will cause a |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1751 | suspension return. The surrounding application must then arrange to discard |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1752 | the recorded number of bytes before it resumes loading the input buffer. |
| 1753 | (Yes, this design is rather baroque, but it avoids complexity in the far more |
| 1754 | common case where a non-suspending source manager is used.) |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1755 | |
| 1756 | If the input data has been exhausted, we recommend that you emit a warning |
| 1757 | and insert dummy EOI markers just as a non-suspending data source manager |
| 1758 | would do. This can be handled either in the surrounding application logic or |
| 1759 | within fill_input_buffer(); the latter is probably more efficient. If |
| 1760 | fill_input_buffer() knows that no more data is available, it can set the |
| 1761 | pointer/count to point to a dummy EOI marker and then return TRUE just as |
| 1762 | though it had read more data in a non-suspending situation. |
| 1763 | |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 1764 | The decompressor does not attempt to suspend within standard JPEG markers; |
| 1765 | instead it will backtrack to the start of the marker and reprocess the whole |
| 1766 | marker next time. Hence the input buffer must be large enough to hold the |
| 1767 | longest standard marker in the file. Standard JPEG markers should normally |
| 1768 | not exceed a few hundred bytes each (DHT tables are typically the longest). |
| 1769 | We recommend at least a 2K buffer for performance reasons, which is much |
| 1770 | larger than any correct marker is likely to be. For robustness against |
| 1771 | damaged marker length counts, you may wish to insert a test in your |
| 1772 | application for the case that the input buffer is completely full and yet |
| 1773 | the decoder has suspended without consuming any data --- otherwise, if this |
| 1774 | situation did occur, it would lead to an endless loop. (The library can't |
| 1775 | provide this test since it has no idea whether "the buffer is full", or |
| 1776 | even whether there is a fixed-size input buffer.) |
| 1777 | |
| 1778 | The input buffer would need to be 64K to allow for arbitrary COM or APPn |
| 1779 | markers, but these are handled specially: they are either saved into allocated |
| 1780 | memory, or skipped over by calling skip_input_data(). In the former case, |
| 1781 | suspension is handled correctly, and in the latter case, the problem of |
| 1782 | buffer overrun is placed on skip_input_data's shoulders, as explained above. |
| 1783 | Note that if you provide your own marker handling routine for large markers, |
| 1784 | you should consider how to deal with buffer overflow. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 1785 | |
Thomas G. Lane | 9ba2f5e | 1994-12-07 00:00:00 +0000 | [diff] [blame] | 1786 | Multiple-buffer management: |
| 1787 | |
| 1788 | In some applications it is desirable to store the compressed data in a linked |
| 1789 | list of buffer areas, so as to avoid data copying. This can be handled by |
| 1790 | having empty_output_buffer() or fill_input_buffer() set the pointer and count |
| 1791 | to reference the next available buffer; FALSE is returned only if no more |
| 1792 | buffers are available. Although seemingly straightforward, there is a |
| 1793 | pitfall in this approach: the backtrack that occurs when FALSE is returned |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1794 | could back up into an earlier buffer. For example, when fill_input_buffer() |
| 1795 | is called, the current pointer & count indicate the backtrack restart point. |
| 1796 | Since fill_input_buffer() will set the pointer and count to refer to a new |
| 1797 | buffer, the restart position must be saved somewhere else. Suppose a second |
| 1798 | call to fill_input_buffer() occurs in the same library call, and no |
| 1799 | additional input data is available, so fill_input_buffer must return FALSE. |
| 1800 | If the JPEG library has not moved the pointer/count forward in the current |
| 1801 | buffer, then *the correct restart point is the saved position in the prior |
| 1802 | buffer*. Prior buffers may be discarded only after the library establishes |
| 1803 | a restart point within a later buffer. Similar remarks apply for output into |
| 1804 | a chain of buffers. |
| 1805 | |
| 1806 | The library will never attempt to backtrack over a skip_input_data() call, |
| 1807 | so any skipped data can be permanently discarded. You still have to deal |
| 1808 | with the case of skipping not-yet-received data, however. |
| 1809 | |
| 1810 | It's much simpler to use only a single buffer; when fill_input_buffer() is |
| 1811 | called, move any unconsumed data (beyond the current pointer/count) down to |
| 1812 | the beginning of this buffer and then load new data into the remaining buffer |
| 1813 | space. This approach requires a little more data copying but is far easier |
| 1814 | to get right. |
| 1815 | |
| 1816 | |
| 1817 | Progressive JPEG support |
| 1818 | ------------------------ |
| 1819 | |
| 1820 | Progressive JPEG rearranges the stored data into a series of scans of |
| 1821 | increasing quality. In situations where a JPEG file is transmitted across a |
| 1822 | slow communications link, a decoder can generate a low-quality image very |
| 1823 | quickly from the first scan, then gradually improve the displayed quality as |
| 1824 | more scans are received. The final image after all scans are complete is |
| 1825 | identical to that of a regular (sequential) JPEG file of the same quality |
| 1826 | setting. Progressive JPEG files are often slightly smaller than equivalent |
| 1827 | sequential JPEG files, but the possibility of incremental display is the main |
| 1828 | reason for using progressive JPEG. |
| 1829 | |
| 1830 | The IJG encoder library generates progressive JPEG files when given a |
| 1831 | suitable "scan script" defining how to divide the data into scans. |
| 1832 | Creation of progressive JPEG files is otherwise transparent to the encoder. |
| 1833 | Progressive JPEG files can also be read transparently by the decoder library. |
| 1834 | If the decoding application simply uses the library as defined above, it |
| 1835 | will receive a final decoded image without any indication that the file was |
| 1836 | progressive. Of course, this approach does not allow incremental display. |
| 1837 | To perform incremental display, an application needs to use the decoder |
| 1838 | library's "buffered-image" mode, in which it receives a decoded image |
| 1839 | multiple times. |
| 1840 | |
| 1841 | Each displayed scan requires about as much work to decode as a full JPEG |
| 1842 | image of the same size, so the decoder must be fairly fast in relation to the |
| 1843 | data transmission rate in order to make incremental display useful. However, |
| 1844 | it is possible to skip displaying the image and simply add the incoming bits |
| 1845 | to the decoder's coefficient buffer. This is fast because only Huffman |
| 1846 | decoding need be done, not IDCT, upsampling, colorspace conversion, etc. |
| 1847 | The IJG decoder library allows the application to switch dynamically between |
| 1848 | displaying the image and simply absorbing the incoming bits. A properly |
| 1849 | coded application can automatically adapt the number of display passes to |
| 1850 | suit the time available as the image is received. Also, a final |
| 1851 | higher-quality display cycle can be performed from the buffered data after |
| 1852 | the end of the file is reached. |
| 1853 | |
| 1854 | Progressive compression: |
| 1855 | |
| 1856 | To create a progressive JPEG file (or a multiple-scan sequential JPEG file), |
| 1857 | set the scan_info cinfo field to point to an array of scan descriptors, and |
| 1858 | perform compression as usual. Instead of constructing your own scan list, |
| 1859 | you can call the jpeg_simple_progression() helper routine to create a |
| 1860 | recommended progression sequence; this method should be used by all |
| 1861 | applications that don't want to get involved in the nitty-gritty of |
| 1862 | progressive scan sequence design. (If you want to provide user control of |
| 1863 | scan sequences, you may wish to borrow the scan script reading code found |
| 1864 | in rdswitch.c, so that you can read scan script files just like cjpeg's.) |
| 1865 | When scan_info is not NULL, the compression library will store DCT'd data |
| 1866 | into a buffer array as jpeg_write_scanlines() is called, and will emit all |
| 1867 | the requested scans during jpeg_finish_compress(). This implies that |
| 1868 | multiple-scan output cannot be created with a suspending data destination |
| 1869 | manager, since jpeg_finish_compress() does not support suspension. We |
| 1870 | should also note that the compressor currently forces Huffman optimization |
| 1871 | mode when creating a progressive JPEG file, because the default Huffman |
| 1872 | tables are unsuitable for progressive files. |
| 1873 | |
| 1874 | Progressive decompression: |
| 1875 | |
| 1876 | When buffered-image mode is not used, the decoder library will read all of |
| 1877 | a multi-scan file during jpeg_start_decompress(), so that it can provide a |
| 1878 | final decoded image. (Here "multi-scan" means either progressive or |
| 1879 | multi-scan sequential.) This makes multi-scan files transparent to the |
| 1880 | decoding application. However, existing applications that used suspending |
| 1881 | input with version 5 of the IJG library will need to be modified to check |
| 1882 | for a suspension return from jpeg_start_decompress(). |
| 1883 | |
| 1884 | To perform incremental display, an application must use the library's |
| 1885 | buffered-image mode. This is described in the next section. |
| 1886 | |
| 1887 | |
| 1888 | Buffered-image mode |
| 1889 | ------------------- |
| 1890 | |
| 1891 | In buffered-image mode, the library stores the partially decoded image in a |
| 1892 | coefficient buffer, from which it can be read out as many times as desired. |
| 1893 | This mode is typically used for incremental display of progressive JPEG files, |
| 1894 | but it can be used with any JPEG file. Each scan of a progressive JPEG file |
| 1895 | adds more data (more detail) to the buffered image. The application can |
| 1896 | display in lockstep with the source file (one display pass per input scan), |
| 1897 | or it can allow input processing to outrun display processing. By making |
| 1898 | input and display processing run independently, it is possible for the |
| 1899 | application to adapt progressive display to a wide range of data transmission |
| 1900 | rates. |
| 1901 | |
| 1902 | The basic control flow for buffered-image decoding is |
| 1903 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1904 | jpeg_create_decompress() |
| 1905 | set data source |
| 1906 | jpeg_read_header() |
| 1907 | set overall decompression parameters |
| 1908 | cinfo.buffered_image = TRUE; /* select buffered-image mode */ |
| 1909 | jpeg_start_decompress() |
| 1910 | for (each output pass) { |
| 1911 | adjust output decompression parameters if required |
| 1912 | jpeg_start_output() /* start a new output pass */ |
| 1913 | for (all scanlines in image) { |
| 1914 | jpeg_read_scanlines() |
| 1915 | display scanlines |
| 1916 | } |
| 1917 | jpeg_finish_output() /* terminate output pass */ |
| 1918 | } |
| 1919 | jpeg_finish_decompress() |
| 1920 | jpeg_destroy_decompress() |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1921 | |
| 1922 | This differs from ordinary unbuffered decoding in that there is an additional |
| 1923 | level of looping. The application can choose how many output passes to make |
| 1924 | and how to display each pass. |
| 1925 | |
| 1926 | The simplest approach to displaying progressive images is to do one display |
| 1927 | pass for each scan appearing in the input file. In this case the outer loop |
| 1928 | condition is typically |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1929 | while (! jpeg_input_complete(&cinfo)) |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1930 | and the start-output call should read |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1931 | jpeg_start_output(&cinfo, cinfo.input_scan_number); |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1932 | The second parameter to jpeg_start_output() indicates which scan of the input |
| 1933 | file is to be displayed; the scans are numbered starting at 1 for this |
| 1934 | purpose. (You can use a loop counter starting at 1 if you like, but using |
| 1935 | the library's input scan counter is easier.) The library automatically reads |
| 1936 | data as necessary to complete each requested scan, and jpeg_finish_output() |
| 1937 | advances to the next scan or end-of-image marker (hence input_scan_number |
| 1938 | will be incremented by the time control arrives back at jpeg_start_output()). |
| 1939 | With this technique, data is read from the input file only as needed, and |
| 1940 | input and output processing run in lockstep. |
| 1941 | |
| 1942 | After reading the final scan and reaching the end of the input file, the |
| 1943 | buffered image remains available; it can be read additional times by |
| 1944 | repeating the jpeg_start_output()/jpeg_read_scanlines()/jpeg_finish_output() |
| 1945 | sequence. For example, a useful technique is to use fast one-pass color |
| 1946 | quantization for display passes made while the image is arriving, followed by |
| 1947 | a final display pass using two-pass quantization for highest quality. This |
| 1948 | is done by changing the library parameters before the final output pass. |
| 1949 | Changing parameters between passes is discussed in detail below. |
| 1950 | |
| 1951 | In general the last scan of a progressive file cannot be recognized as such |
| 1952 | until after it is read, so a post-input display pass is the best approach if |
| 1953 | you want special processing in the final pass. |
| 1954 | |
| 1955 | When done with the image, be sure to call jpeg_finish_decompress() to release |
| 1956 | the buffered image (or just use jpeg_destroy_decompress()). |
| 1957 | |
| 1958 | If input data arrives faster than it can be displayed, the application can |
| 1959 | cause the library to decode input data in advance of what's needed to produce |
| 1960 | output. This is done by calling the routine jpeg_consume_input(). |
| 1961 | The return value is one of the following: |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 1962 | JPEG_REACHED_SOS: reached an SOS marker (the start of a new scan) |
| 1963 | JPEG_REACHED_EOI: reached the EOI marker (end of image) |
| 1964 | JPEG_ROW_COMPLETED: completed reading one MCU row of compressed data |
| 1965 | JPEG_SCAN_COMPLETED: completed reading last MCU row of current scan |
| 1966 | JPEG_SUSPENDED: suspended before completing any of the above |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 1967 | (JPEG_SUSPENDED can occur only if a suspending data source is used.) This |
| 1968 | routine can be called at any time after initializing the JPEG object. It |
| 1969 | reads some additional data and returns when one of the indicated significant |
| 1970 | events occurs. (If called after the EOI marker is reached, it will |
| 1971 | immediately return JPEG_REACHED_EOI without attempting to read more data.) |
| 1972 | |
| 1973 | The library's output processing will automatically call jpeg_consume_input() |
| 1974 | whenever the output processing overtakes the input; thus, simple lockstep |
| 1975 | display requires no direct calls to jpeg_consume_input(). But by adding |
| 1976 | calls to jpeg_consume_input(), you can absorb data in advance of what is |
| 1977 | being displayed. This has two benefits: |
| 1978 | * You can limit buildup of unprocessed data in your input buffer. |
| 1979 | * You can eliminate extra display passes by paying attention to the |
| 1980 | state of the library's input processing. |
| 1981 | |
| 1982 | The first of these benefits only requires interspersing calls to |
| 1983 | jpeg_consume_input() with your display operations and any other processing |
| 1984 | you may be doing. To avoid wasting cycles due to backtracking, it's best to |
| 1985 | call jpeg_consume_input() only after a hundred or so new bytes have arrived. |
| 1986 | This is discussed further under "I/O suspension", above. (Note: the JPEG |
| 1987 | library currently is not thread-safe. You must not call jpeg_consume_input() |
| 1988 | from one thread of control if a different library routine is working on the |
| 1989 | same JPEG object in another thread.) |
| 1990 | |
| 1991 | When input arrives fast enough that more than one new scan is available |
| 1992 | before you start a new output pass, you may as well skip the output pass |
| 1993 | corresponding to the completed scan. This occurs for free if you pass |
| 1994 | cinfo.input_scan_number as the target scan number to jpeg_start_output(). |
| 1995 | The input_scan_number field is simply the index of the scan currently being |
| 1996 | consumed by the input processor. You can ensure that this is up-to-date by |
| 1997 | emptying the input buffer just before calling jpeg_start_output(): call |
| 1998 | jpeg_consume_input() repeatedly until it returns JPEG_SUSPENDED or |
| 1999 | JPEG_REACHED_EOI. |
| 2000 | |
| 2001 | The target scan number passed to jpeg_start_output() is saved in the |
| 2002 | cinfo.output_scan_number field. The library's output processing calls |
| 2003 | jpeg_consume_input() whenever the current input scan number and row within |
Thomas G. Lane | 489583f | 1996-02-07 00:00:00 +0000 | [diff] [blame] | 2004 | that scan is less than or equal to the current output scan number and row. |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2005 | Thus, input processing can "get ahead" of the output processing but is not |
| 2006 | allowed to "fall behind". You can achieve several different effects by |
| 2007 | manipulating this interlock rule. For example, if you pass a target scan |
| 2008 | number greater than the current input scan number, the output processor will |
| 2009 | wait until that scan starts to arrive before producing any output. (To avoid |
| 2010 | an infinite loop, the target scan number is automatically reset to the last |
| 2011 | scan number when the end of image is reached. Thus, if you specify a large |
| 2012 | target scan number, the library will just absorb the entire input file and |
| 2013 | then perform an output pass. This is effectively the same as what |
| 2014 | jpeg_start_decompress() does when you don't select buffered-image mode.) |
| 2015 | When you pass a target scan number equal to the current input scan number, |
| 2016 | the image is displayed no faster than the current input scan arrives. The |
| 2017 | final possibility is to pass a target scan number less than the current input |
| 2018 | scan number; this disables the input/output interlock and causes the output |
| 2019 | processor to simply display whatever it finds in the image buffer, without |
| 2020 | waiting for input. (However, the library will not accept a target scan |
| 2021 | number less than one, so you can't avoid waiting for the first scan.) |
| 2022 | |
Thomas G. Lane | 489583f | 1996-02-07 00:00:00 +0000 | [diff] [blame] | 2023 | When data is arriving faster than the output display processing can advance |
| 2024 | through the image, jpeg_consume_input() will store data into the buffered |
| 2025 | image beyond the point at which the output processing is reading data out |
| 2026 | again. If the input arrives fast enough, it may "wrap around" the buffer to |
| 2027 | the point where the input is more than one whole scan ahead of the output. |
| 2028 | If the output processing simply proceeds through its display pass without |
| 2029 | paying attention to the input, the effect seen on-screen is that the lower |
| 2030 | part of the image is one or more scans better in quality than the upper part. |
| 2031 | Then, when the next output scan is started, you have a choice of what target |
| 2032 | scan number to use. The recommended choice is to use the current input scan |
| 2033 | number at that time, which implies that you've skipped the output scans |
| 2034 | corresponding to the input scans that were completed while you processed the |
| 2035 | previous output scan. In this way, the decoder automatically adapts its |
| 2036 | speed to the arriving data, by skipping output scans as necessary to keep up |
| 2037 | with the arriving data. |
| 2038 | |
| 2039 | When using this strategy, you'll want to be sure that you perform a final |
| 2040 | output pass after receiving all the data; otherwise your last display may not |
| 2041 | be full quality across the whole screen. So the right outer loop logic is |
| 2042 | something like this: |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 2043 | do { |
| 2044 | absorb any waiting input by calling jpeg_consume_input() |
| 2045 | final_pass = jpeg_input_complete(&cinfo); |
| 2046 | adjust output decompression parameters if required |
| 2047 | jpeg_start_output(&cinfo, cinfo.input_scan_number); |
| 2048 | ... |
| 2049 | jpeg_finish_output() |
| 2050 | } while (! final_pass); |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2051 | rather than quitting as soon as jpeg_input_complete() returns TRUE. This |
| 2052 | arrangement makes it simple to use higher-quality decoding parameters |
| 2053 | for the final pass. But if you don't want to use special parameters for |
| 2054 | the final pass, the right loop logic is like this: |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 2055 | for (;;) { |
| 2056 | absorb any waiting input by calling jpeg_consume_input() |
| 2057 | jpeg_start_output(&cinfo, cinfo.input_scan_number); |
| 2058 | ... |
| 2059 | jpeg_finish_output() |
| 2060 | if (jpeg_input_complete(&cinfo) && |
| 2061 | cinfo.input_scan_number == cinfo.output_scan_number) |
| 2062 | break; |
| 2063 | } |
Thomas G. Lane | 489583f | 1996-02-07 00:00:00 +0000 | [diff] [blame] | 2064 | In this case you don't need to know in advance whether an output pass is to |
| 2065 | be the last one, so it's not necessary to have reached EOF before starting |
| 2066 | the final output pass; rather, what you want to test is whether the output |
| 2067 | pass was performed in sync with the final input scan. This form of the loop |
| 2068 | will avoid an extra output pass whenever the decoder is able (or nearly able) |
| 2069 | to keep up with the incoming data. |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2070 | |
| 2071 | When the data transmission speed is high, you might begin a display pass, |
Thomas G. Lane | 489583f | 1996-02-07 00:00:00 +0000 | [diff] [blame] | 2072 | then find that much or all of the file has arrived before you can complete |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2073 | the pass. (You can detect this by noting the JPEG_REACHED_EOI return code |
| 2074 | from jpeg_consume_input(), or equivalently by testing jpeg_input_complete().) |
| 2075 | In this situation you may wish to abort the current display pass and start a |
| 2076 | new one using the newly arrived information. To do so, just call |
| 2077 | jpeg_finish_output() and then start a new pass with jpeg_start_output(). |
| 2078 | |
| 2079 | A variant strategy is to abort and restart display if more than one complete |
| 2080 | scan arrives during an output pass; this can be detected by noting |
| 2081 | JPEG_REACHED_SOS returns and/or examining cinfo.input_scan_number. This |
| 2082 | idea should be employed with caution, however, since the display process |
| 2083 | might never get to the bottom of the image before being aborted, resulting |
| 2084 | in the lower part of the screen being several passes worse than the upper. |
| 2085 | In most cases it's probably best to abort an output pass only if the whole |
| 2086 | file has arrived and you want to begin the final output pass immediately. |
| 2087 | |
| 2088 | When receiving data across a communication link, we recommend always using |
| 2089 | the current input scan number for the output target scan number; if a |
| 2090 | higher-quality final pass is to be done, it should be started (aborting any |
| 2091 | incomplete output pass) as soon as the end of file is received. However, |
| 2092 | many other strategies are possible. For example, the application can examine |
| 2093 | the parameters of the current input scan and decide whether to display it or |
| 2094 | not. If the scan contains only chroma data, one might choose not to use it |
| 2095 | as the target scan, expecting that the scan will be small and will arrive |
| 2096 | quickly. To skip to the next scan, call jpeg_consume_input() until it |
| 2097 | returns JPEG_REACHED_SOS or JPEG_REACHED_EOI. Or just use the next higher |
| 2098 | number as the target scan for jpeg_start_output(); but that method doesn't |
| 2099 | let you inspect the next scan's parameters before deciding to display it. |
| 2100 | |
| 2101 | |
| 2102 | In buffered-image mode, jpeg_start_decompress() never performs input and |
| 2103 | thus never suspends. An application that uses input suspension with |
| 2104 | buffered-image mode must be prepared for suspension returns from these |
| 2105 | routines: |
| 2106 | * jpeg_start_output() performs input only if you request 2-pass quantization |
| 2107 | and the target scan isn't fully read yet. (This is discussed below.) |
| 2108 | * jpeg_read_scanlines(), as always, returns the number of scanlines that it |
| 2109 | was able to produce before suspending. |
| 2110 | * jpeg_finish_output() will read any markers following the target scan, |
Thomas G. Lane | 489583f | 1996-02-07 00:00:00 +0000 | [diff] [blame] | 2111 | up to the end of the file or the SOS marker that begins another scan. |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2112 | (But it reads no input if jpeg_consume_input() has already reached the |
Thomas G. Lane | 489583f | 1996-02-07 00:00:00 +0000 | [diff] [blame] | 2113 | end of the file or a SOS marker beyond the target output scan.) |
| 2114 | * jpeg_finish_decompress() will read until the end of file, and thus can |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2115 | suspend if the end hasn't already been reached (as can be tested by |
| 2116 | calling jpeg_input_complete()). |
| 2117 | jpeg_start_output(), jpeg_finish_output(), and jpeg_finish_decompress() |
| 2118 | all return TRUE if they completed their tasks, FALSE if they had to suspend. |
| 2119 | In the event of a FALSE return, the application must load more input data |
| 2120 | and repeat the call. Applications that use non-suspending data sources need |
| 2121 | not check the return values of these three routines. |
| 2122 | |
| 2123 | |
| 2124 | It is possible to change decoding parameters between output passes in the |
| 2125 | buffered-image mode. The decoder library currently supports only very |
| 2126 | limited changes of parameters. ONLY THE FOLLOWING parameter changes are |
| 2127 | allowed after jpeg_start_decompress() is called: |
| 2128 | * dct_method can be changed before each call to jpeg_start_output(). |
| 2129 | For example, one could use a fast DCT method for early scans, changing |
| 2130 | to a higher quality method for the final scan. |
| 2131 | * dither_mode can be changed before each call to jpeg_start_output(); |
| 2132 | of course this has no impact if not using color quantization. Typically |
| 2133 | one would use ordered dither for initial passes, then switch to |
| 2134 | Floyd-Steinberg dither for the final pass. Caution: changing dither mode |
| 2135 | can cause more memory to be allocated by the library. Although the amount |
| 2136 | of memory involved is not large (a scanline or so), it may cause the |
| 2137 | initial max_memory_to_use specification to be exceeded, which in the worst |
| 2138 | case would result in an out-of-memory failure. |
| 2139 | * do_block_smoothing can be changed before each call to jpeg_start_output(). |
| 2140 | This setting is relevant only when decoding a progressive JPEG image. |
| 2141 | During the first DC-only scan, block smoothing provides a very "fuzzy" look |
| 2142 | instead of the very "blocky" look seen without it; which is better seems a |
| 2143 | matter of personal taste. But block smoothing is nearly always a win |
| 2144 | during later stages, especially when decoding a successive-approximation |
| 2145 | image: smoothing helps to hide the slight blockiness that otherwise shows |
| 2146 | up on smooth gradients until the lowest coefficient bits are sent. |
| 2147 | * Color quantization mode can be changed under the rules described below. |
| 2148 | You *cannot* change between full-color and quantized output (because that |
| 2149 | would alter the required I/O buffer sizes), but you can change which |
| 2150 | quantization method is used. |
| 2151 | |
| 2152 | When generating color-quantized output, changing quantization method is a |
| 2153 | very useful way of switching between high-speed and high-quality display. |
| 2154 | The library allows you to change among its three quantization methods: |
| 2155 | 1. Single-pass quantization to a fixed color cube. |
| 2156 | Selected by cinfo.two_pass_quantize = FALSE and cinfo.colormap = NULL. |
| 2157 | 2. Single-pass quantization to an application-supplied colormap. |
| 2158 | Selected by setting cinfo.colormap to point to the colormap (the value of |
| 2159 | two_pass_quantize is ignored); also set cinfo.actual_number_of_colors. |
| 2160 | 3. Two-pass quantization to a colormap chosen specifically for the image. |
| 2161 | Selected by cinfo.two_pass_quantize = TRUE and cinfo.colormap = NULL. |
| 2162 | (This is the default setting selected by jpeg_read_header, but it is |
| 2163 | probably NOT what you want for the first pass of progressive display!) |
| 2164 | These methods offer successively better quality and lesser speed. However, |
| 2165 | only the first method is available for quantizing in non-RGB color spaces. |
| 2166 | |
| 2167 | IMPORTANT: because the different quantizer methods have very different |
| 2168 | working-storage requirements, the library requires you to indicate which |
| 2169 | one(s) you intend to use before you call jpeg_start_decompress(). (If we did |
| 2170 | not require this, the max_memory_to_use setting would be a complete fiction.) |
| 2171 | You do this by setting one or more of these three cinfo fields to TRUE: |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 2172 | enable_1pass_quant Fixed color cube colormap |
| 2173 | enable_external_quant Externally-supplied colormap |
| 2174 | enable_2pass_quant Two-pass custom colormap |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2175 | All three are initialized FALSE by jpeg_read_header(). But |
| 2176 | jpeg_start_decompress() automatically sets TRUE the one selected by the |
| 2177 | current two_pass_quantize and colormap settings, so you only need to set the |
| 2178 | enable flags for any other quantization methods you plan to change to later. |
| 2179 | |
| 2180 | After setting the enable flags correctly at jpeg_start_decompress() time, you |
| 2181 | can change to any enabled quantization method by setting two_pass_quantize |
| 2182 | and colormap properly just before calling jpeg_start_output(). The following |
| 2183 | special rules apply: |
| 2184 | 1. You must explicitly set cinfo.colormap to NULL when switching to 1-pass |
| 2185 | or 2-pass mode from a different mode, or when you want the 2-pass |
| 2186 | quantizer to be re-run to generate a new colormap. |
| 2187 | 2. To switch to an external colormap, or to change to a different external |
| 2188 | colormap than was used on the prior pass, you must call |
| 2189 | jpeg_new_colormap() after setting cinfo.colormap. |
| 2190 | NOTE: if you want to use the same colormap as was used in the prior pass, |
| 2191 | you should not do either of these things. This will save some nontrivial |
| 2192 | switchover costs. |
| 2193 | (These requirements exist because cinfo.colormap will always be non-NULL |
| 2194 | after completing a prior output pass, since both the 1-pass and 2-pass |
| 2195 | quantizers set it to point to their output colormaps. Thus you have to |
| 2196 | do one of these two things to notify the library that something has changed. |
| 2197 | Yup, it's a bit klugy, but it's necessary to do it this way for backwards |
| 2198 | compatibility.) |
| 2199 | |
| 2200 | Note that in buffered-image mode, the library generates any requested colormap |
| 2201 | during jpeg_start_output(), not during jpeg_start_decompress(). |
| 2202 | |
| 2203 | When using two-pass quantization, jpeg_start_output() makes a pass over the |
| 2204 | buffered image to determine the optimum color map; it therefore may take a |
| 2205 | significant amount of time, whereas ordinarily it does little work. The |
| 2206 | progress monitor hook is called during this pass, if defined. It is also |
| 2207 | important to realize that if the specified target scan number is greater than |
| 2208 | or equal to the current input scan number, jpeg_start_output() will attempt |
| 2209 | to consume input as it makes this pass. If you use a suspending data source, |
| 2210 | you need to check for a FALSE return from jpeg_start_output() under these |
| 2211 | conditions. The combination of 2-pass quantization and a not-yet-fully-read |
| 2212 | target scan is the only case in which jpeg_start_output() will consume input. |
| 2213 | |
| 2214 | |
| 2215 | Application authors who support buffered-image mode may be tempted to use it |
| 2216 | for all JPEG images, even single-scan ones. This will work, but it is |
| 2217 | inefficient: there is no need to create an image-sized coefficient buffer for |
| 2218 | single-scan images. Requesting buffered-image mode for such an image wastes |
| 2219 | memory. Worse, it can cost time on large images, since the buffered data has |
| 2220 | to be swapped out or written to a temporary file. If you are concerned about |
| 2221 | maximum performance on baseline JPEG files, you should use buffered-image |
| 2222 | mode only when the incoming file actually has multiple scans. This can be |
| 2223 | tested by calling jpeg_has_multiple_scans(), which will return a correct |
| 2224 | result at any time after jpeg_read_header() completes. |
| 2225 | |
| 2226 | It is also worth noting that when you use jpeg_consume_input() to let input |
| 2227 | processing get ahead of output processing, the resulting pattern of access to |
| 2228 | the coefficient buffer is quite nonsequential. It's best to use the memory |
| 2229 | manager jmemnobs.c if you can (ie, if you have enough real or virtual main |
| 2230 | memory). If not, at least make sure that max_memory_to_use is set as high as |
| 2231 | possible. If the JPEG memory manager has to use a temporary file, you will |
| 2232 | probably see a lot of disk traffic and poor performance. (This could be |
| 2233 | improved with additional work on the memory manager, but we haven't gotten |
| 2234 | around to it yet.) |
| 2235 | |
| 2236 | In some applications it may be convenient to use jpeg_consume_input() for all |
| 2237 | input processing, including reading the initial markers; that is, you may |
| 2238 | wish to call jpeg_consume_input() instead of jpeg_read_header() during |
| 2239 | startup. This works, but note that you must check for JPEG_REACHED_SOS and |
| 2240 | JPEG_REACHED_EOI return codes as the equivalent of jpeg_read_header's codes. |
| 2241 | Once the first SOS marker has been reached, you must call |
| 2242 | jpeg_start_decompress() before jpeg_consume_input() will consume more input; |
| 2243 | it'll just keep returning JPEG_REACHED_SOS until you do. If you read a |
| 2244 | tables-only file this way, jpeg_consume_input() will return JPEG_REACHED_EOI |
| 2245 | without ever returning JPEG_REACHED_SOS; be sure to check for this case. |
| 2246 | If this happens, the decompressor will not read any more input until you call |
| 2247 | jpeg_abort() to reset it. It is OK to call jpeg_consume_input() even when not |
| 2248 | using buffered-image mode, but in that case it's basically a no-op after the |
| 2249 | initial markers have been read: it will just return JPEG_SUSPENDED. |
Thomas G. Lane | 9ba2f5e | 1994-12-07 00:00:00 +0000 | [diff] [blame] | 2250 | |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2251 | |
| 2252 | Abbreviated datastreams and multiple images |
| 2253 | ------------------------------------------- |
| 2254 | |
| 2255 | A JPEG compression or decompression object can be reused to process multiple |
| 2256 | images. This saves a small amount of time per image by eliminating the |
| 2257 | "create" and "destroy" operations, but that isn't the real purpose of the |
| 2258 | feature. Rather, reuse of an object provides support for abbreviated JPEG |
| 2259 | datastreams. Object reuse can also simplify processing a series of images in |
| 2260 | a single input or output file. This section explains these features. |
| 2261 | |
| 2262 | A JPEG file normally contains several hundred bytes worth of quantization |
| 2263 | and Huffman tables. In a situation where many images will be stored or |
| 2264 | transmitted with identical tables, this may represent an annoying overhead. |
| 2265 | The JPEG standard therefore permits tables to be omitted. The standard |
| 2266 | defines three classes of JPEG datastreams: |
| 2267 | * "Interchange" datastreams contain an image and all tables needed to decode |
| 2268 | the image. These are the usual kind of JPEG file. |
| 2269 | * "Abbreviated image" datastreams contain an image, but are missing some or |
| 2270 | all of the tables needed to decode that image. |
| 2271 | * "Abbreviated table specification" (henceforth "tables-only") datastreams |
| 2272 | contain only table specifications. |
| 2273 | To decode an abbreviated image, it is necessary to load the missing table(s) |
| 2274 | into the decoder beforehand. This can be accomplished by reading a separate |
| 2275 | tables-only file. A variant scheme uses a series of images in which the first |
| 2276 | image is an interchange (complete) datastream, while subsequent ones are |
| 2277 | abbreviated and rely on the tables loaded by the first image. It is assumed |
| 2278 | that once the decoder has read a table, it will remember that table until a |
| 2279 | new definition for the same table number is encountered. |
| 2280 | |
| 2281 | It is the application designer's responsibility to figure out how to associate |
| 2282 | the correct tables with an abbreviated image. While abbreviated datastreams |
| 2283 | can be useful in a closed environment, their use is strongly discouraged in |
| 2284 | any situation where data exchange with other applications might be needed. |
| 2285 | Caveat designer. |
| 2286 | |
| 2287 | The JPEG library provides support for reading and writing any combination of |
| 2288 | tables-only datastreams and abbreviated images. In both compression and |
| 2289 | decompression objects, a quantization or Huffman table will be retained for |
| 2290 | the lifetime of the object, unless it is overwritten by a new table definition. |
| 2291 | |
| 2292 | |
| 2293 | To create abbreviated image datastreams, it is only necessary to tell the |
| 2294 | compressor not to emit some or all of the tables it is using. Each |
| 2295 | quantization and Huffman table struct contains a boolean field "sent_table", |
| 2296 | which normally is initialized to FALSE. For each table used by the image, the |
| 2297 | header-writing process emits the table and sets sent_table = TRUE unless it is |
| 2298 | already TRUE. (In normal usage, this prevents outputting the same table |
| 2299 | definition multiple times, as would otherwise occur because the chroma |
| 2300 | components typically share tables.) Thus, setting this field to TRUE before |
| 2301 | calling jpeg_start_compress() will prevent the table from being written at |
| 2302 | all. |
| 2303 | |
| 2304 | If you want to create a "pure" abbreviated image file containing no tables, |
| 2305 | just call "jpeg_suppress_tables(&cinfo, TRUE)" after constructing all the |
| 2306 | tables. If you want to emit some but not all tables, you'll need to set the |
| 2307 | individual sent_table fields directly. |
| 2308 | |
| 2309 | To create an abbreviated image, you must also call jpeg_start_compress() |
| 2310 | with a second parameter of FALSE, not TRUE. Otherwise jpeg_start_compress() |
| 2311 | will force all the sent_table fields to FALSE. (This is a safety feature to |
| 2312 | prevent abbreviated images from being created accidentally.) |
| 2313 | |
| 2314 | To create a tables-only file, perform the same parameter setup that you |
| 2315 | normally would, but instead of calling jpeg_start_compress() and so on, call |
| 2316 | jpeg_write_tables(&cinfo). This will write an abbreviated datastream |
| 2317 | containing only SOI, DQT and/or DHT markers, and EOI. All the quantization |
| 2318 | and Huffman tables that are currently defined in the compression object will |
| 2319 | be emitted unless their sent_tables flag is already TRUE, and then all the |
| 2320 | sent_tables flags will be set TRUE. |
| 2321 | |
| 2322 | A sure-fire way to create matching tables-only and abbreviated image files |
| 2323 | is to proceed as follows: |
| 2324 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 2325 | create JPEG compression object |
| 2326 | set JPEG parameters |
| 2327 | set destination to tables-only file |
| 2328 | jpeg_write_tables(&cinfo); |
| 2329 | set destination to image file |
| 2330 | jpeg_start_compress(&cinfo, FALSE); |
| 2331 | write data... |
| 2332 | jpeg_finish_compress(&cinfo); |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2333 | |
| 2334 | Since the JPEG parameters are not altered between writing the table file and |
| 2335 | the abbreviated image file, the same tables are sure to be used. Of course, |
| 2336 | you can repeat the jpeg_start_compress() ... jpeg_finish_compress() sequence |
| 2337 | many times to produce many abbreviated image files matching the table file. |
| 2338 | |
| 2339 | You cannot suppress output of the computed Huffman tables when Huffman |
| 2340 | optimization is selected. (If you could, there'd be no way to decode the |
| 2341 | image...) Generally, you don't want to set optimize_coding = TRUE when |
| 2342 | you are trying to produce abbreviated files. |
| 2343 | |
| 2344 | In some cases you might want to compress an image using tables which are |
| 2345 | not stored in the application, but are defined in an interchange or |
| 2346 | tables-only file readable by the application. This can be done by setting up |
| 2347 | a JPEG decompression object to read the specification file, then copying the |
Thomas G. Lane | 489583f | 1996-02-07 00:00:00 +0000 | [diff] [blame] | 2348 | tables into your compression object. See jpeg_copy_critical_parameters() |
| 2349 | for an example of copying quantization tables. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2350 | |
| 2351 | |
| 2352 | To read abbreviated image files, you simply need to load the proper tables |
| 2353 | into the decompression object before trying to read the abbreviated image. |
| 2354 | If the proper tables are stored in the application program, you can just |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 2355 | allocate the table structs and fill in their contents directly. For example, |
| 2356 | to load a fixed quantization table into table slot "n": |
| 2357 | |
| 2358 | if (cinfo.quant_tbl_ptrs[n] == NULL) |
| 2359 | cinfo.quant_tbl_ptrs[n] = jpeg_alloc_quant_table((j_common_ptr) &cinfo); |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 2360 | quant_ptr = cinfo.quant_tbl_ptrs[n]; /* quant_ptr is JQUANT_TBL* */ |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 2361 | for (i = 0; i < 64; i++) { |
| 2362 | /* Qtable[] is desired quantization table, in natural array order */ |
| 2363 | quant_ptr->quantval[i] = Qtable[i]; |
| 2364 | } |
| 2365 | |
| 2366 | Code to load a fixed Huffman table is typically (for AC table "n"): |
| 2367 | |
| 2368 | if (cinfo.ac_huff_tbl_ptrs[n] == NULL) |
| 2369 | cinfo.ac_huff_tbl_ptrs[n] = jpeg_alloc_huff_table((j_common_ptr) &cinfo); |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 2370 | huff_ptr = cinfo.ac_huff_tbl_ptrs[n]; /* huff_ptr is JHUFF_TBL* */ |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 2371 | for (i = 1; i <= 16; i++) { |
| 2372 | /* counts[i] is number of Huffman codes of length i bits, i=1..16 */ |
| 2373 | huff_ptr->bits[i] = counts[i]; |
| 2374 | } |
| 2375 | for (i = 0; i < 256; i++) { |
| 2376 | /* symbols[] is the list of Huffman symbols, in code-length order */ |
| 2377 | huff_ptr->huffval[i] = symbols[i]; |
| 2378 | } |
| 2379 | |
| 2380 | (Note that trying to set cinfo.quant_tbl_ptrs[n] to point directly at a |
| 2381 | constant JQUANT_TBL object is not safe. If the incoming file happened to |
| 2382 | contain a quantization table definition, your master table would get |
| 2383 | overwritten! Instead allocate a working table copy and copy the master table |
| 2384 | into it, as illustrated above. Ditto for Huffman tables, of course.) |
| 2385 | |
| 2386 | You might want to read the tables from a tables-only file, rather than |
| 2387 | hard-wiring them into your application. The jpeg_read_header() call is |
| 2388 | sufficient to read a tables-only file. You must pass a second parameter of |
| 2389 | FALSE to indicate that you do not require an image to be present. Thus, the |
| 2390 | typical scenario is |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2391 | |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 2392 | create JPEG decompression object |
| 2393 | set source to tables-only file |
| 2394 | jpeg_read_header(&cinfo, FALSE); |
| 2395 | set source to abbreviated image file |
| 2396 | jpeg_read_header(&cinfo, TRUE); |
| 2397 | set decompression parameters |
| 2398 | jpeg_start_decompress(&cinfo); |
| 2399 | read data... |
| 2400 | jpeg_finish_decompress(&cinfo); |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2401 | |
| 2402 | In some cases, you may want to read a file without knowing whether it contains |
| 2403 | an image or just tables. In that case, pass FALSE and check the return value |
| 2404 | from jpeg_read_header(): it will be JPEG_HEADER_OK if an image was found, |
| 2405 | JPEG_HEADER_TABLES_ONLY if only tables were found. (A third return value, |
| 2406 | JPEG_SUSPENDED, is possible when using a suspending data source manager.) |
| 2407 | Note that jpeg_read_header() will not complain if you read an abbreviated |
| 2408 | image for which you haven't loaded the missing tables; the missing-table check |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2409 | occurs later, in jpeg_start_decompress(). |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2410 | |
| 2411 | |
| 2412 | It is possible to read a series of images from a single source file by |
| 2413 | repeating the jpeg_read_header() ... jpeg_finish_decompress() sequence, |
| 2414 | without releasing/recreating the JPEG object or the data source module. |
| 2415 | (If you did reinitialize, any partial bufferload left in the data source |
| 2416 | buffer at the end of one image would be discarded, causing you to lose the |
| 2417 | start of the next image.) When you use this method, stored tables are |
| 2418 | automatically carried forward, so some of the images can be abbreviated images |
| 2419 | that depend on tables from earlier images. |
| 2420 | |
| 2421 | If you intend to write a series of images into a single destination file, |
| 2422 | you might want to make a specialized data destination module that doesn't |
| 2423 | flush the output buffer at term_destination() time. This would speed things |
| 2424 | up by some trifling amount. Of course, you'd need to remember to flush the |
| 2425 | buffer after the last image. You can make the later images be abbreviated |
| 2426 | ones by passing FALSE to jpeg_start_compress(). |
| 2427 | |
| 2428 | |
| 2429 | Special markers |
| 2430 | --------------- |
| 2431 | |
| 2432 | Some applications may need to insert or extract special data in the JPEG |
| 2433 | datastream. The JPEG standard provides marker types "COM" (comment) and |
| 2434 | "APP0" through "APP15" (application) to hold application-specific data. |
| 2435 | Unfortunately, the use of these markers is not specified by the standard. |
| 2436 | COM markers are fairly widely used to hold user-supplied text. The JFIF file |
| 2437 | format spec uses APP0 markers with specified initial strings to hold certain |
| 2438 | data. Adobe applications use APP14 markers beginning with the string "Adobe" |
| 2439 | for miscellaneous data. Other APPn markers are rarely seen, but might |
| 2440 | contain almost anything. |
| 2441 | |
| 2442 | If you wish to store user-supplied text, we recommend you use COM markers |
| 2443 | and place readable 7-bit ASCII text in them. Newline conventions are not |
| 2444 | standardized --- expect to find LF (Unix style), CR/LF (DOS style), or CR |
| 2445 | (Mac style). A robust COM reader should be able to cope with random binary |
| 2446 | garbage, including nulls, since some applications generate COM markers |
| 2447 | containing non-ASCII junk. (But yours should not be one of them.) |
| 2448 | |
| 2449 | For program-supplied data, use an APPn marker, and be sure to begin it with an |
| 2450 | identifying string so that you can tell whether the marker is actually yours. |
| 2451 | It's probably best to avoid using APP0 or APP14 for any private markers. |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2452 | (NOTE: the upcoming SPIFF standard will use APP8 markers; we recommend you |
| 2453 | not use APP8 markers for any private purposes, either.) |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2454 | |
| 2455 | Keep in mind that at most 65533 bytes can be put into one marker, but you |
| 2456 | can have as many markers as you like. |
| 2457 | |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2458 | By default, the IJG compression library will write a JFIF APP0 marker if the |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2459 | selected JPEG colorspace is grayscale or YCbCr, or an Adobe APP14 marker if |
| 2460 | the selected colorspace is RGB, CMYK, or YCCK. You can disable this, but |
| 2461 | we don't recommend it. The decompression library will recognize JFIF and |
| 2462 | Adobe markers and will set the JPEG colorspace properly when one is found. |
| 2463 | |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 2464 | |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2465 | You can write special markers immediately following the datastream header by |
| 2466 | calling jpeg_write_marker() after jpeg_start_compress() and before the first |
| 2467 | call to jpeg_write_scanlines(). When you do this, the markers appear after |
| 2468 | the SOI and the JFIF APP0 and Adobe APP14 markers (if written), but before |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2469 | all else. Specify the marker type parameter as "JPEG_COM" for COM or |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2470 | "JPEG_APP0 + n" for APPn. (Actually, jpeg_write_marker will let you write |
| 2471 | any marker type, but we don't recommend writing any other kinds of marker.) |
| 2472 | For example, to write a user comment string pointed to by comment_text: |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 2473 | jpeg_write_marker(cinfo, JPEG_COM, comment_text, strlen(comment_text)); |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2474 | |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 2475 | If it's not convenient to store all the marker data in memory at once, |
| 2476 | you can instead call jpeg_write_m_header() followed by multiple calls to |
| 2477 | jpeg_write_m_byte(). If you do it this way, it's your responsibility to |
| 2478 | call jpeg_write_m_byte() exactly the number of times given in the length |
| 2479 | parameter to jpeg_write_m_header(). (This method lets you empty the |
| 2480 | output buffer partway through a marker, which might be important when |
| 2481 | using a suspending data destination module. In any case, if you are using |
| 2482 | a suspending destination, you should flush its buffer after inserting |
| 2483 | any special markers. See "I/O suspension".) |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2484 | |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 2485 | Or, if you prefer to synthesize the marker byte sequence yourself, |
| 2486 | you can just cram it straight into the data destination module. |
| 2487 | |
| 2488 | If you are writing JFIF 1.02 extension markers (thumbnail images), don't |
| 2489 | forget to set cinfo.JFIF_minor_version = 2 so that the encoder will write the |
| 2490 | correct JFIF version number in the JFIF header marker. The library's default |
| 2491 | is to write version 1.01, but that's wrong if you insert any 1.02 extension |
| 2492 | markers. (We could probably get away with just defaulting to 1.02, but there |
| 2493 | used to be broken decoders that would complain about unknown minor version |
| 2494 | numbers. To reduce compatibility risks it's safest not to write 1.02 unless |
| 2495 | you are actually using 1.02 extensions.) |
| 2496 | |
| 2497 | |
| 2498 | When reading, two methods of handling special markers are available: |
| 2499 | 1. You can ask the library to save the contents of COM and/or APPn markers |
| 2500 | into memory, and then examine them at your leisure afterwards. |
| 2501 | 2. You can supply your own routine to process COM and/or APPn markers |
| 2502 | on-the-fly as they are read. |
| 2503 | The first method is simpler to use, especially if you are using a suspending |
| 2504 | data source; writing a marker processor that copes with input suspension is |
| 2505 | not easy (consider what happens if the marker is longer than your available |
| 2506 | input buffer). However, the second method conserves memory since the marker |
| 2507 | data need not be kept around after it's been processed. |
| 2508 | |
| 2509 | For either method, you'd normally set up marker handling after creating a |
| 2510 | decompression object and before calling jpeg_read_header(), because the |
| 2511 | markers of interest will typically be near the head of the file and so will |
| 2512 | be scanned by jpeg_read_header. Once you've established a marker handling |
| 2513 | method, it will be used for the life of that decompression object |
| 2514 | (potentially many datastreams), unless you change it. Marker handling is |
| 2515 | determined separately for COM markers and for each APPn marker code. |
| 2516 | |
| 2517 | |
| 2518 | To save the contents of special markers in memory, call |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 2519 | jpeg_save_markers(cinfo, marker_code, length_limit) |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 2520 | where marker_code is the marker type to save, JPEG_COM or JPEG_APP0+n. |
| 2521 | (To arrange to save all the special marker types, you need to call this |
| 2522 | routine 17 times, for COM and APP0-APP15.) If the incoming marker is longer |
| 2523 | than length_limit data bytes, only length_limit bytes will be saved; this |
| 2524 | parameter allows you to avoid chewing up memory when you only need to see the |
| 2525 | first few bytes of a potentially large marker. If you want to save all the |
| 2526 | data, set length_limit to 0xFFFF; that is enough since marker lengths are only |
| 2527 | 16 bits. As a special case, setting length_limit to 0 prevents that marker |
| 2528 | type from being saved at all. (That is the default behavior, in fact.) |
| 2529 | |
| 2530 | After jpeg_read_header() completes, you can examine the special markers by |
| 2531 | following the cinfo->marker_list pointer chain. All the special markers in |
| 2532 | the file appear in this list, in order of their occurrence in the file (but |
| 2533 | omitting any markers of types you didn't ask for). Both the original data |
| 2534 | length and the saved data length are recorded for each list entry; the latter |
| 2535 | will not exceed length_limit for the particular marker type. Note that these |
| 2536 | lengths exclude the marker length word, whereas the stored representation |
| 2537 | within the JPEG file includes it. (Hence the maximum data length is really |
| 2538 | only 65533.) |
| 2539 | |
| 2540 | It is possible that additional special markers appear in the file beyond the |
| 2541 | SOS marker at which jpeg_read_header stops; if so, the marker list will be |
| 2542 | extended during reading of the rest of the file. This is not expected to be |
| 2543 | common, however. If you are short on memory you may want to reset the length |
| 2544 | limit to zero for all marker types after finishing jpeg_read_header, to |
| 2545 | ensure that the max_memory_to_use setting cannot be exceeded due to addition |
| 2546 | of later markers. |
| 2547 | |
| 2548 | The marker list remains stored until you call jpeg_finish_decompress or |
| 2549 | jpeg_abort, at which point the memory is freed and the list is set to empty. |
| 2550 | (jpeg_destroy also releases the storage, of course.) |
| 2551 | |
| 2552 | Note that the library is internally interested in APP0 and APP14 markers; |
| 2553 | if you try to set a small nonzero length limit on these types, the library |
| 2554 | will silently force the length up to the minimum it wants. (But you can set |
| 2555 | a zero length limit to prevent them from being saved at all.) Also, in a |
| 2556 | 16-bit environment, the maximum length limit may be constrained to less than |
| 2557 | 65533 by malloc() limitations. It is therefore best not to assume that the |
| 2558 | effective length limit is exactly what you set it to be. |
| 2559 | |
| 2560 | |
| 2561 | If you want to supply your own marker-reading routine, you do it by calling |
| 2562 | jpeg_set_marker_processor(). A marker processor routine must have the |
| 2563 | signature |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 2564 | boolean jpeg_marker_parser_method (j_decompress_ptr cinfo) |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2565 | Although the marker code is not explicitly passed, the routine can find it |
| 2566 | in cinfo->unread_marker. At the time of call, the marker proper has been |
| 2567 | read from the data source module. The processor routine is responsible for |
| 2568 | reading the marker length word and the remaining parameter bytes, if any. |
| 2569 | Return TRUE to indicate success. (FALSE should be returned only if you are |
| 2570 | using a suspending data source and it tells you to suspend. See the standard |
| 2571 | marker processors in jdmarker.c for appropriate coding methods if you need to |
| 2572 | use a suspending data source.) |
| 2573 | |
| 2574 | If you override the default APP0 or APP14 processors, it is up to you to |
| 2575 | recognize JFIF and Adobe markers if you want colorspace recognition to occur |
| 2576 | properly. We recommend copying and extending the default processors if you |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 2577 | want to do that. (A better idea is to save these marker types for later |
| 2578 | examination by calling jpeg_save_markers(); that method doesn't interfere |
| 2579 | with the library's own processing of these markers.) |
| 2580 | |
| 2581 | jpeg_set_marker_processor() and jpeg_save_markers() are mutually exclusive |
| 2582 | --- if you call one it overrides any previous call to the other, for the |
| 2583 | particular marker type specified. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2584 | |
| 2585 | A simple example of an external COM processor can be found in djpeg.c. |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 2586 | Also, see jpegtran.c for an example of using jpeg_save_markers. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2587 | |
| 2588 | |
| 2589 | Raw (downsampled) image data |
| 2590 | ---------------------------- |
| 2591 | |
| 2592 | Some applications need to supply already-downsampled image data to the JPEG |
| 2593 | compressor, or to receive raw downsampled data from the decompressor. The |
| 2594 | library supports this requirement by allowing the application to write or |
| 2595 | read raw data, bypassing the normal preprocessing or postprocessing steps. |
| 2596 | The interface is different from the standard one and is somewhat harder to |
| 2597 | use. If your interest is merely in bypassing color conversion, we recommend |
| 2598 | that you use the standard interface and simply set jpeg_color_space = |
| 2599 | in_color_space (or jpeg_color_space = out_color_space for decompression). |
| 2600 | The mechanism described in this section is necessary only to supply or |
| 2601 | receive downsampled image data, in which not all components have the same |
| 2602 | dimensions. |
| 2603 | |
| 2604 | |
| 2605 | To compress raw data, you must supply the data in the colorspace to be used |
| 2606 | in the JPEG file (please read the earlier section on Special color spaces) |
| 2607 | and downsampled to the sampling factors specified in the JPEG parameters. |
| 2608 | You must supply the data in the format used internally by the JPEG library, |
| 2609 | namely a JSAMPIMAGE array. This is an array of pointers to two-dimensional |
| 2610 | arrays, each of type JSAMPARRAY. Each 2-D array holds the values for one |
| 2611 | color component. This structure is necessary since the components are of |
| 2612 | different sizes. If the image dimensions are not a multiple of the MCU size, |
| 2613 | you must also pad the data correctly (usually, this is done by replicating |
| 2614 | the last column and/or row). The data must be padded to a multiple of a DCT |
| 2615 | block in each component: that is, each downsampled row must contain a |
| 2616 | multiple of 8 valid samples, and there must be a multiple of 8 sample rows |
| 2617 | for each component. (For applications such as conversion of digital TV |
| 2618 | images, the standard image size is usually a multiple of the DCT block size, |
| 2619 | so that no padding need actually be done.) |
| 2620 | |
| 2621 | The procedure for compression of raw data is basically the same as normal |
| 2622 | compression, except that you call jpeg_write_raw_data() in place of |
| 2623 | jpeg_write_scanlines(). Before calling jpeg_start_compress(), you must do |
| 2624 | the following: |
| 2625 | * Set cinfo->raw_data_in to TRUE. (It is set FALSE by jpeg_set_defaults().) |
| 2626 | This notifies the library that you will be supplying raw data. |
| 2627 | * Ensure jpeg_color_space is correct --- an explicit jpeg_set_colorspace() |
| 2628 | call is a good idea. Note that since color conversion is bypassed, |
| 2629 | in_color_space is ignored, except that jpeg_set_defaults() uses it to |
| 2630 | choose the default jpeg_color_space setting. |
| 2631 | * Ensure the sampling factors, cinfo->comp_info[i].h_samp_factor and |
| 2632 | cinfo->comp_info[i].v_samp_factor, are correct. Since these indicate the |
| 2633 | dimensions of the data you are supplying, it's wise to set them |
| 2634 | explicitly, rather than assuming the library's defaults are what you want. |
| 2635 | |
| 2636 | To pass raw data to the library, call jpeg_write_raw_data() in place of |
| 2637 | jpeg_write_scanlines(). The two routines work similarly except that |
| 2638 | jpeg_write_raw_data takes a JSAMPIMAGE data array rather than JSAMPARRAY. |
| 2639 | The scanlines count passed to and returned from jpeg_write_raw_data is |
| 2640 | measured in terms of the component with the largest v_samp_factor. |
| 2641 | |
| 2642 | jpeg_write_raw_data() processes one MCU row per call, which is to say |
| 2643 | v_samp_factor*DCTSIZE sample rows of each component. The passed num_lines |
| 2644 | value must be at least max_v_samp_factor*DCTSIZE, and the return value will |
| 2645 | be exactly that amount (or possibly some multiple of that amount, in future |
| 2646 | library versions). This is true even on the last call at the bottom of the |
| 2647 | image; don't forget to pad your data as necessary. |
| 2648 | |
| 2649 | The required dimensions of the supplied data can be computed for each |
| 2650 | component as |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 2651 | cinfo->comp_info[i].width_in_blocks*DCTSIZE samples per row |
| 2652 | cinfo->comp_info[i].height_in_blocks*DCTSIZE rows in image |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2653 | after jpeg_start_compress() has initialized those fields. If the valid data |
| 2654 | is smaller than this, it must be padded appropriately. For some sampling |
| 2655 | factors and image sizes, additional dummy DCT blocks are inserted to make |
| 2656 | the image a multiple of the MCU dimensions. The library creates such dummy |
| 2657 | blocks itself; it does not read them from your supplied data. Therefore you |
| 2658 | need never pad by more than DCTSIZE samples. An example may help here. |
| 2659 | Assume 2h2v downsampling of YCbCr data, that is |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 2660 | cinfo->comp_info[0].h_samp_factor = 2 for Y |
| 2661 | cinfo->comp_info[0].v_samp_factor = 2 |
| 2662 | cinfo->comp_info[1].h_samp_factor = 1 for Cb |
| 2663 | cinfo->comp_info[1].v_samp_factor = 1 |
| 2664 | cinfo->comp_info[2].h_samp_factor = 1 for Cr |
| 2665 | cinfo->comp_info[2].v_samp_factor = 1 |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2666 | and suppose that the nominal image dimensions (cinfo->image_width and |
| 2667 | cinfo->image_height) are 101x101 pixels. Then jpeg_start_compress() will |
| 2668 | compute downsampled_width = 101 and width_in_blocks = 13 for Y, |
| 2669 | downsampled_width = 51 and width_in_blocks = 7 for Cb and Cr (and the same |
| 2670 | for the height fields). You must pad the Y data to at least 13*8 = 104 |
| 2671 | columns and rows, the Cb/Cr data to at least 7*8 = 56 columns and rows. The |
| 2672 | MCU height is max_v_samp_factor = 2 DCT rows so you must pass at least 16 |
| 2673 | scanlines on each call to jpeg_write_raw_data(), which is to say 16 actual |
| 2674 | sample rows of Y and 8 each of Cb and Cr. A total of 7 MCU rows are needed, |
| 2675 | so you must pass a total of 7*16 = 112 "scanlines". The last DCT block row |
| 2676 | of Y data is dummy, so it doesn't matter what you pass for it in the data |
| 2677 | arrays, but the scanlines count must total up to 112 so that all of the Cb |
| 2678 | and Cr data gets passed. |
| 2679 | |
Thomas G. Lane | a8b67c4 | 1995-03-15 00:00:00 +0000 | [diff] [blame] | 2680 | Output suspension is supported with raw-data compression: if the data |
| 2681 | destination module suspends, jpeg_write_raw_data() will return 0. |
| 2682 | In this case the same data rows must be passed again on the next call. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2683 | |
| 2684 | |
| 2685 | Decompression with raw data output implies bypassing all postprocessing: |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2686 | you cannot ask for rescaling or color quantization, for instance. More |
| 2687 | seriously, you must deal with the color space and sampling factors present in |
| 2688 | the incoming file. If your application only handles, say, 2h1v YCbCr data, |
| 2689 | you must check for and fail on other color spaces or other sampling factors. |
| 2690 | The library will not convert to a different color space for you. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2691 | |
| 2692 | To obtain raw data output, set cinfo->raw_data_out = TRUE before |
| 2693 | jpeg_start_decompress() (it is set FALSE by jpeg_read_header()). Be sure to |
| 2694 | verify that the color space and sampling factors are ones you can handle. |
| 2695 | Then call jpeg_read_raw_data() in place of jpeg_read_scanlines(). The |
| 2696 | decompression process is otherwise the same as usual. |
| 2697 | |
| 2698 | jpeg_read_raw_data() returns one MCU row per call, and thus you must pass a |
| 2699 | buffer of at least max_v_samp_factor*DCTSIZE scanlines (scanline counting is |
| 2700 | the same as for raw-data compression). The buffer you pass must be large |
| 2701 | enough to hold the actual data plus padding to DCT-block boundaries. As with |
| 2702 | compression, any entirely dummy DCT blocks are not processed so you need not |
| 2703 | allocate space for them, but the total scanline count includes them. The |
| 2704 | above example of computing buffer dimensions for raw-data compression is |
| 2705 | equally valid for decompression. |
| 2706 | |
| 2707 | Input suspension is supported with raw-data decompression: if the data source |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2708 | module suspends, jpeg_read_raw_data() will return 0. You can also use |
| 2709 | buffered-image mode to read raw data in multiple passes. |
| 2710 | |
| 2711 | |
| 2712 | Really raw data: DCT coefficients |
| 2713 | --------------------------------- |
| 2714 | |
| 2715 | It is possible to read or write the contents of a JPEG file as raw DCT |
| 2716 | coefficients. This facility is mainly intended for use in lossless |
| 2717 | transcoding between different JPEG file formats. Other possible applications |
| 2718 | include lossless cropping of a JPEG image, lossless reassembly of a |
| 2719 | multi-strip or multi-tile TIFF/JPEG file into a single JPEG datastream, etc. |
| 2720 | |
| 2721 | To read the contents of a JPEG file as DCT coefficients, open the file and do |
| 2722 | jpeg_read_header() as usual. But instead of calling jpeg_start_decompress() |
| 2723 | and jpeg_read_scanlines(), call jpeg_read_coefficients(). This will read the |
| 2724 | entire image into a set of virtual coefficient-block arrays, one array per |
| 2725 | component. The return value is a pointer to an array of virtual-array |
| 2726 | descriptors. Each virtual array can be accessed directly using the JPEG |
| 2727 | memory manager's access_virt_barray method (see Memory management, below, |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 2728 | and also read structure.txt's discussion of virtual array handling). Or, |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2729 | for simple transcoding to a different JPEG file format, the array list can |
| 2730 | just be handed directly to jpeg_write_coefficients(). |
| 2731 | |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 2732 | Each block in the block arrays contains quantized coefficient values in |
| 2733 | normal array order (not JPEG zigzag order). The block arrays contain only |
| 2734 | DCT blocks containing real data; any entirely-dummy blocks added to fill out |
| 2735 | interleaved MCUs at the right or bottom edges of the image are discarded |
| 2736 | during reading and are not stored in the block arrays. (The size of each |
| 2737 | block array can be determined from the width_in_blocks and height_in_blocks |
| 2738 | fields of the component's comp_info entry.) This is also the data format |
| 2739 | expected by jpeg_write_coefficients(). |
| 2740 | |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2741 | When you are done using the virtual arrays, call jpeg_finish_decompress() |
| 2742 | to release the array storage and return the decompression object to an idle |
| 2743 | state; or just call jpeg_destroy() if you don't need to reuse the object. |
| 2744 | |
| 2745 | If you use a suspending data source, jpeg_read_coefficients() will return |
| 2746 | NULL if it is forced to suspend; a non-NULL return value indicates successful |
| 2747 | completion. You need not test for a NULL return value when using a |
| 2748 | non-suspending data source. |
| 2749 | |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 2750 | It is also possible to call jpeg_read_coefficients() to obtain access to the |
| 2751 | decoder's coefficient arrays during a normal decode cycle in buffered-image |
| 2752 | mode. This frammish might be useful for progressively displaying an incoming |
| 2753 | image and then re-encoding it without loss. To do this, decode in buffered- |
| 2754 | image mode as discussed previously, then call jpeg_read_coefficients() after |
| 2755 | the last jpeg_finish_output() call. The arrays will be available for your use |
| 2756 | until you call jpeg_finish_decompress(). |
| 2757 | |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2758 | |
| 2759 | To write the contents of a JPEG file as DCT coefficients, you must provide |
| 2760 | the DCT coefficients stored in virtual block arrays. You can either pass |
| 2761 | block arrays read from an input JPEG file by jpeg_read_coefficients(), or |
| 2762 | allocate virtual arrays from the JPEG compression object and fill them |
| 2763 | yourself. In either case, jpeg_write_coefficients() is substituted for |
| 2764 | jpeg_start_compress() and jpeg_write_scanlines(). Thus the sequence is |
| 2765 | * Create compression object |
| 2766 | * Set all compression parameters as necessary |
| 2767 | * Request virtual arrays if needed |
| 2768 | * jpeg_write_coefficients() |
| 2769 | * jpeg_finish_compress() |
| 2770 | * Destroy or re-use compression object |
| 2771 | jpeg_write_coefficients() is passed a pointer to an array of virtual block |
| 2772 | array descriptors; the number of arrays is equal to cinfo.num_components. |
| 2773 | |
| 2774 | The virtual arrays need only have been requested, not realized, before |
| 2775 | jpeg_write_coefficients() is called. A side-effect of |
| 2776 | jpeg_write_coefficients() is to realize any virtual arrays that have been |
| 2777 | requested from the compression object's memory manager. Thus, when obtaining |
| 2778 | the virtual arrays from the compression object, you should fill the arrays |
| 2779 | after calling jpeg_write_coefficients(). The data is actually written out |
| 2780 | when you call jpeg_finish_compress(); jpeg_write_coefficients() only writes |
| 2781 | the file header. |
| 2782 | |
| 2783 | When writing raw DCT coefficients, it is crucial that the JPEG quantization |
| 2784 | tables and sampling factors match the way the data was encoded, or the |
| 2785 | resulting file will be invalid. For transcoding from an existing JPEG file, |
| 2786 | we recommend using jpeg_copy_critical_parameters(). This routine initializes |
| 2787 | all the compression parameters to default values (like jpeg_set_defaults()), |
| 2788 | then copies the critical information from a source decompression object. |
| 2789 | The decompression object should have just been used to read the entire |
| 2790 | JPEG input file --- that is, it should be awaiting jpeg_finish_decompress(). |
| 2791 | |
| 2792 | jpeg_write_coefficients() marks all tables stored in the compression object |
| 2793 | as needing to be written to the output file (thus, it acts like |
| 2794 | jpeg_start_compress(cinfo, TRUE)). This is for safety's sake, to avoid |
| 2795 | emitting abbreviated JPEG files by accident. If you really want to emit an |
| 2796 | abbreviated JPEG file, call jpeg_suppress_tables(), or set the tables' |
| 2797 | individual sent_table flags, between calling jpeg_write_coefficients() and |
| 2798 | jpeg_finish_compress(). |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2799 | |
| 2800 | |
| 2801 | Progress monitoring |
| 2802 | ------------------- |
| 2803 | |
| 2804 | Some applications may need to regain control from the JPEG library every so |
| 2805 | often. The typical use of this feature is to produce a percent-done bar or |
| 2806 | other progress display. (For a simple example, see cjpeg.c or djpeg.c.) |
| 2807 | Although you do get control back frequently during the data-transferring pass |
| 2808 | (the jpeg_read_scanlines or jpeg_write_scanlines loop), any additional passes |
| 2809 | will occur inside jpeg_finish_compress or jpeg_start_decompress; those |
| 2810 | routines may take a long time to execute, and you don't get control back |
| 2811 | until they are done. |
| 2812 | |
| 2813 | You can define a progress-monitor routine which will be called periodically |
| 2814 | by the library. No guarantees are made about how often this call will occur, |
| 2815 | so we don't recommend you use it for mouse tracking or anything like that. |
| 2816 | At present, a call will occur once per MCU row, scanline, or sample row |
| 2817 | group, whichever unit is convenient for the current processing mode; so the |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2818 | wider the image, the longer the time between calls. During the data |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2819 | transferring pass, only one call occurs per call of jpeg_read_scanlines or |
| 2820 | jpeg_write_scanlines, so don't pass a large number of scanlines at once if |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2821 | you want fine resolution in the progress count. (If you really need to use |
| 2822 | the callback mechanism for time-critical tasks like mouse tracking, you could |
| 2823 | insert additional calls inside some of the library's inner loops.) |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2824 | |
| 2825 | To establish a progress-monitor callback, create a struct jpeg_progress_mgr, |
| 2826 | fill in its progress_monitor field with a pointer to your callback routine, |
| 2827 | and set cinfo->progress to point to the struct. The callback will be called |
| 2828 | whenever cinfo->progress is non-NULL. (This pointer is set to NULL by |
| 2829 | jpeg_create_compress or jpeg_create_decompress; the library will not change |
| 2830 | it thereafter. So if you allocate dynamic storage for the progress struct, |
| 2831 | make sure it will live as long as the JPEG object does. Allocating from the |
| 2832 | JPEG memory manager with lifetime JPOOL_PERMANENT will work nicely.) You |
| 2833 | can use the same callback routine for both compression and decompression. |
| 2834 | |
| 2835 | The jpeg_progress_mgr struct contains four fields which are set by the library: |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 2836 | long pass_counter; /* work units completed in this pass */ |
| 2837 | long pass_limit; /* total number of work units in this pass */ |
| 2838 | int completed_passes; /* passes completed so far */ |
| 2839 | int total_passes; /* total number of passes expected */ |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2840 | During any one pass, pass_counter increases from 0 up to (not including) |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2841 | pass_limit; the step size is usually but not necessarily 1. The pass_limit |
| 2842 | value may change from one pass to another. The expected total number of |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2843 | passes is in total_passes, and the number of passes already completed is in |
| 2844 | completed_passes. Thus the fraction of work completed may be estimated as |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 2845 | completed_passes + (pass_counter/pass_limit) |
| 2846 | -------------------------------------------- |
| 2847 | total_passes |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2848 | ignoring the fact that the passes may not be equal amounts of work. |
| 2849 | |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2850 | When decompressing, pass_limit can even change within a pass, because it |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2851 | depends on the number of scans in the JPEG file, which isn't always known in |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2852 | advance. The computed fraction-of-work-done may jump suddenly (if the library |
| 2853 | discovers it has overestimated the number of scans) or even decrease (in the |
| 2854 | opposite case). It is not wise to put great faith in the work estimate. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2855 | |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2856 | When using the decompressor's buffered-image mode, the progress monitor work |
| 2857 | estimate is likely to be completely unhelpful, because the library has no way |
| 2858 | to know how many output passes will be demanded of it. Currently, the library |
| 2859 | sets total_passes based on the assumption that there will be one more output |
| 2860 | pass if the input file end hasn't yet been read (jpeg_input_complete() isn't |
| 2861 | TRUE), but no more output passes if the file end has been reached when the |
| 2862 | output pass is started. This means that total_passes will rise as additional |
| 2863 | output passes are requested. If you have a way of determining the input file |
| 2864 | size, estimating progress based on the fraction of the file that's been read |
| 2865 | will probably be more useful than using the library's value. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2866 | |
| 2867 | |
| 2868 | Memory management |
| 2869 | ----------------- |
| 2870 | |
| 2871 | This section covers some key facts about the JPEG library's built-in memory |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 2872 | manager. For more info, please read structure.txt's section about the memory |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2873 | manager, and consult the source code if necessary. |
| 2874 | |
| 2875 | All memory and temporary file allocation within the library is done via the |
| 2876 | memory manager. If necessary, you can replace the "back end" of the memory |
| 2877 | manager to control allocation yourself (for example, if you don't want the |
| 2878 | library to use malloc() and free() for some reason). |
| 2879 | |
| 2880 | Some data is allocated "permanently" and will not be freed until the JPEG |
| 2881 | object is destroyed. Most data is allocated "per image" and is freed by |
| 2882 | jpeg_finish_compress, jpeg_finish_decompress, or jpeg_abort. You can call the |
| 2883 | memory manager yourself to allocate structures that will automatically be |
| 2884 | freed at these times. Typical code for this is |
| 2885 | ptr = (*cinfo->mem->alloc_small) ((j_common_ptr) cinfo, JPOOL_IMAGE, size); |
| 2886 | Use JPOOL_PERMANENT to get storage that lasts as long as the JPEG object. |
| 2887 | Use alloc_large instead of alloc_small for anything bigger than a few Kbytes. |
| 2888 | There are also alloc_sarray and alloc_barray routines that automatically |
| 2889 | build 2-D sample or block arrays. |
| 2890 | |
| 2891 | The library's minimum space requirements to process an image depend on the |
| 2892 | image's width, but not on its height, because the library ordinarily works |
| 2893 | with "strip" buffers that are as wide as the image but just a few rows high. |
| 2894 | Some operating modes (eg, two-pass color quantization) require full-image |
| 2895 | buffers. Such buffers are treated as "virtual arrays": only the current strip |
| 2896 | need be in memory, and the rest can be swapped out to a temporary file. |
| 2897 | |
| 2898 | If you use the simplest memory manager back end (jmemnobs.c), then no |
| 2899 | temporary files are used; virtual arrays are simply malloc()'d. Images bigger |
| 2900 | than memory can be processed only if your system supports virtual memory. |
| 2901 | The other memory manager back ends support temporary files of various flavors |
| 2902 | and thus work in machines without virtual memory. They may also be useful on |
| 2903 | Unix machines if you need to process images that exceed available swap space. |
| 2904 | |
| 2905 | When using temporary files, the library will make the in-memory buffers for |
| 2906 | its virtual arrays just big enough to stay within a "maximum memory" setting. |
| 2907 | Your application can set this limit by setting cinfo->mem->max_memory_to_use |
| 2908 | after creating the JPEG object. (Of course, there is still a minimum size for |
| 2909 | the buffers, so the max-memory setting is effective only if it is bigger than |
| 2910 | the minimum space needed.) If you allocate any large structures yourself, you |
| 2911 | must allocate them before jpeg_start_compress() or jpeg_start_decompress() in |
| 2912 | order to have them counted against the max memory limit. Also keep in mind |
| 2913 | that space allocated with alloc_small() is ignored, on the assumption that |
Thomas G. Lane | bc79e06 | 1995-08-02 00:00:00 +0000 | [diff] [blame] | 2914 | it's too small to be worth worrying about; so a reasonable safety margin |
| 2915 | should be left when setting max_memory_to_use. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2916 | |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2917 | |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 2918 | Memory usage |
| 2919 | ------------ |
| 2920 | |
| 2921 | Working memory requirements while performing compression or decompression |
| 2922 | depend on image dimensions, image characteristics (such as colorspace and |
| 2923 | JPEG process), and operating mode (application-selected options). |
| 2924 | |
| 2925 | As of v6b, the decompressor requires: |
| 2926 | 1. About 24K in more-or-less-fixed-size data. This varies a bit depending |
| 2927 | on operating mode and image characteristics (particularly color vs. |
| 2928 | grayscale), but it doesn't depend on image dimensions. |
| 2929 | 2. Strip buffers (of size proportional to the image width) for IDCT and |
| 2930 | upsampling results. The worst case for commonly used sampling factors |
| 2931 | is about 34 bytes * width in pixels for a color image. A grayscale image |
| 2932 | only needs about 8 bytes per pixel column. |
| 2933 | 3. A full-image DCT coefficient buffer is needed to decode a multi-scan JPEG |
| 2934 | file (including progressive JPEGs), or whenever you select buffered-image |
| 2935 | mode. This takes 2 bytes/coefficient. At typical 2x2 sampling, that's |
| 2936 | 3 bytes per pixel for a color image. Worst case (1x1 sampling) requires |
| 2937 | 6 bytes/pixel. For grayscale, figure 2 bytes/pixel. |
| 2938 | 4. To perform 2-pass color quantization, the decompressor also needs a |
| 2939 | 128K color lookup table and a full-image pixel buffer (3 bytes/pixel). |
| 2940 | This does not count any memory allocated by the application, such as a |
| 2941 | buffer to hold the final output image. |
| 2942 | |
| 2943 | The above figures are valid for 8-bit JPEG data precision and a machine with |
| 2944 | 32-bit ints. For 12-bit JPEG data, double the size of the strip buffers and |
| 2945 | quantization pixel buffer. The "fixed-size" data will be somewhat smaller |
| 2946 | with 16-bit ints, larger with 64-bit ints. Also, CMYK or other unusual |
| 2947 | color spaces will require different amounts of space. |
| 2948 | |
| 2949 | The full-image coefficient and pixel buffers, if needed at all, do not |
| 2950 | have to be fully RAM resident; you can have the library use temporary |
| 2951 | files instead when the total memory usage would exceed a limit you set. |
| 2952 | (But if your OS supports virtual memory, it's probably better to just use |
| 2953 | jmemnobs and let the OS do the swapping.) |
| 2954 | |
| 2955 | The compressor's memory requirements are similar, except that it has no need |
| 2956 | for color quantization. Also, it needs a full-image DCT coefficient buffer |
| 2957 | if Huffman-table optimization is asked for, even if progressive mode is not |
| 2958 | requested. |
| 2959 | |
| 2960 | If you need more detailed information about memory usage in a particular |
| 2961 | situation, you can enable the MEM_STATS code in jmemmgr.c. |
| 2962 | |
| 2963 | |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2964 | Library compile-time options |
| 2965 | ---------------------------- |
| 2966 | |
| 2967 | A number of compile-time options are available by modifying jmorecfg.h. |
| 2968 | |
| 2969 | The JPEG standard provides for both the baseline 8-bit DCT process and |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 2970 | a 12-bit DCT process. The IJG code supports 12-bit lossy JPEG if you define |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2971 | BITS_IN_JSAMPLE as 12 rather than 8. Note that this causes JSAMPLE to be |
| 2972 | larger than a char, so it affects the surrounding application's image data. |
Thomas G. Lane | 9ba2f5e | 1994-12-07 00:00:00 +0000 | [diff] [blame] | 2973 | The sample applications cjpeg and djpeg can support 12-bit mode only for PPM |
| 2974 | and GIF file formats; you must disable the other file formats to compile a |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 2975 | 12-bit cjpeg or djpeg. (install.txt has more information about that.) |
Thomas G. Lane | a8b67c4 | 1995-03-15 00:00:00 +0000 | [diff] [blame] | 2976 | At present, a 12-bit library can handle *only* 12-bit images, not both |
DRC | 52ded87 | 2014-05-15 20:30:16 +0000 | [diff] [blame] | 2977 | precisions. |
Thomas G. Lane | a8b67c4 | 1995-03-15 00:00:00 +0000 | [diff] [blame] | 2978 | |
| 2979 | Note that a 12-bit library always compresses in Huffman optimization mode, |
| 2980 | in order to generate valid Huffman tables. This is necessary because our |
| 2981 | default Huffman tables only cover 8-bit data. If you need to output 12-bit |
| 2982 | files in one pass, you'll have to supply suitable default Huffman tables. |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 2983 | You may also want to supply your own DCT quantization tables; the existing |
| 2984 | quality-scaling code has been developed for 8-bit use, and probably doesn't |
| 2985 | generate especially good tables for 12-bit. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 2986 | |
| 2987 | The maximum number of components (color channels) in the image is determined |
| 2988 | by MAX_COMPONENTS. The JPEG standard allows up to 255 components, but we |
| 2989 | expect that few applications will need more than four or so. |
| 2990 | |
| 2991 | On machines with unusual data type sizes, you may be able to improve |
| 2992 | performance or reduce memory space by tweaking the various typedefs in |
| 2993 | jmorecfg.h. In particular, on some RISC CPUs, access to arrays of "short"s |
| 2994 | is quite slow; consider trading memory for speed by making JCOEF, INT16, and |
| 2995 | UINT16 be "int" or "unsigned int". UINT8 is also a candidate to become int. |
| 2996 | You probably don't want to make JSAMPLE be int unless you have lots of memory |
| 2997 | to burn. |
| 2998 | |
| 2999 | You can reduce the size of the library by compiling out various optional |
| 3000 | functions. To do this, undefine xxx_SUPPORTED symbols as necessary. |
| 3001 | |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 3002 | You can also save a few K by not having text error messages in the library; |
| 3003 | the standard error message table occupies about 5Kb. This is particularly |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 3004 | reasonable for embedded applications where there's no good way to display |
Thomas G. Lane | 5ead57a | 1998-03-27 00:00:00 +0000 | [diff] [blame] | 3005 | a message anyway. To do this, remove the creation of the message table |
| 3006 | (jpeg_std_message_table[]) from jerror.c, and alter format_message to do |
| 3007 | something reasonable without it. You could output the numeric value of the |
| 3008 | message code number, for example. If you do this, you can also save a couple |
| 3009 | more K by modifying the TRACEMSn() macros in jerror.h to expand to nothing; |
| 3010 | you don't need trace capability anyway, right? |
| 3011 | |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 3012 | |
| 3013 | Portability considerations |
| 3014 | -------------------------- |
| 3015 | |
| 3016 | The JPEG library has been written to be extremely portable; the sample |
| 3017 | applications cjpeg and djpeg are slightly less so. This section summarizes |
| 3018 | the design goals in this area. (If you encounter any bugs that cause the |
| 3019 | library to be less portable than is claimed here, we'd appreciate hearing |
| 3020 | about them.) |
| 3021 | |
DRC | fced14c | 2014-05-21 04:13:09 +0000 | [diff] [blame] | 3022 | The code works fine on ANSI C and C++ compilers, using any of the popular |
| 3023 | system include file setups, and some not-so-popular ones too. |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 3024 | |
| 3025 | The code is not dependent on the exact sizes of the C data types. As |
| 3026 | distributed, we make the assumptions that |
DRC | b775351 | 2014-05-11 09:36:25 +0000 | [diff] [blame] | 3027 | char is at least 8 bits wide |
| 3028 | short is at least 16 bits wide |
| 3029 | int is at least 16 bits wide |
| 3030 | long is at least 32 bits wide |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 3031 | (These are the minimum requirements of the ANSI C standard.) Wider types will |
| 3032 | work fine, although memory may be used inefficiently if char is much larger |
| 3033 | than 8 bits or short is much bigger than 16 bits. The code should work |
| 3034 | equally well with 16- or 32-bit ints. |
| 3035 | |
| 3036 | In a system where these assumptions are not met, you may be able to make the |
| 3037 | code work by modifying the typedefs in jmorecfg.h. However, you will probably |
| 3038 | have difficulty if int is less than 16 bits wide, since references to plain |
| 3039 | int abound in the code. |
| 3040 | |
| 3041 | char can be either signed or unsigned, although the code runs faster if an |
| 3042 | unsigned char type is available. If char is wider than 8 bits, you will need |
| 3043 | to redefine JOCTET and/or provide custom data source/destination managers so |
| 3044 | that JOCTET represents exactly 8 bits of data on external storage. |
| 3045 | |
| 3046 | The JPEG library proper does not assume ASCII representation of characters. |
| 3047 | But some of the image file I/O modules in cjpeg/djpeg do have ASCII |
| 3048 | dependencies in file-header manipulation; so does cjpeg's select_file_type() |
| 3049 | routine. |
| 3050 | |
| 3051 | The JPEG library does not rely heavily on the C library. In particular, C |
| 3052 | stdio is used only by the data source/destination modules and the error |
| 3053 | handler, all of which are application-replaceable. (cjpeg/djpeg are more |
| 3054 | heavily dependent on stdio.) malloc and free are called only from the memory |
| 3055 | manager "back end" module, so you can use a different memory allocator by |
| 3056 | replacing that one file. |
| 3057 | |
Guido Vollbeding | 5996a25 | 2009-06-27 00:00:00 +0000 | [diff] [blame] | 3058 | More info about porting the code may be gleaned by reading jconfig.txt, |
Thomas G. Lane | 36a4ccc | 1994-09-24 00:00:00 +0000 | [diff] [blame] | 3059 | jmorecfg.h, and jinclude.h. |