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