Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(191)

Side by Side Diff: libjpeg.txt

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

Powered by Google App Engine
This is Rietveld 408576698