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