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