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