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 M/N with all M from 1 to 16, where 1127 N is the source DCT size, which is 8 for baseline JPEG. (The library 1128 design allows for arbitrary scaling ratios but this is not likely 1129 to be implemented any time soon.) The values are initialized by 1130 jpeg_read_header() with the source DCT size. For baseline JPEG 1131 this is 8/8. If you change only the scale_num value while leaving 1132 the other unchanged, then this specifies the DCT scaled size to be 1133 applied on the given input. For baseline JPEG this is equivalent 1134 to M/8 scaling, since the source DCT size for baseline JPEG is 8. 1135 Smaller scaling ratios permit significantly faster decoding since 1136 fewer pixels need be processed and a simpler IDCT method can be used. 1137 1138boolean quantize_colors 1139 If set TRUE, colormapped output will be delivered. Default is FALSE, 1140 meaning that full-color output will be delivered. 1141 1142The next three parameters are relevant only if quantize_colors is TRUE. 1143 1144int desired_number_of_colors 1145 Maximum number of colors to use in generating a library-supplied color 1146 map (the actual number of colors is returned in a different field). 1147 Default 256. Ignored when the application supplies its own color map. 1148 1149boolean two_pass_quantize 1150 If TRUE, an extra pass over the image is made to select a custom color 1151 map for the image. This usually looks a lot better than the one-size- 1152 fits-all colormap that is used otherwise. Default is TRUE. Ignored 1153 when the application supplies its own color map. 1154 1155J_DITHER_MODE dither_mode 1156 Selects color dithering method. Supported values are: 1157 JDITHER_NONE no dithering: fast, very low quality 1158 JDITHER_ORDERED ordered dither: moderate speed and quality 1159 JDITHER_FS Floyd-Steinberg dither: slow, high quality 1160 Default is JDITHER_FS. (At present, ordered dither is implemented 1161 only in the single-pass, standard-colormap case. If you ask for 1162 ordered dither when two_pass_quantize is TRUE or when you supply 1163 an external color map, you'll get F-S dithering.) 1164 1165When quantize_colors is TRUE, the target color map is described by the next 1166two fields. colormap is set to NULL by jpeg_read_header(). The application 1167can supply a color map by setting colormap non-NULL and setting 1168actual_number_of_colors to the map size. Otherwise, jpeg_start_decompress() 1169selects a suitable color map and sets these two fields itself. 1170[Implementation restriction: at present, an externally supplied colormap is 1171only accepted for 3-component output color spaces.] 1172 1173JSAMPARRAY colormap 1174 The color map, represented as a 2-D pixel array of out_color_components 1175 rows and actual_number_of_colors columns. Ignored if not quantizing. 1176 CAUTION: if the JPEG library creates its own colormap, the storage 1177 pointed to by this field is released by jpeg_finish_decompress(). 1178 Copy the colormap somewhere else first, if you want to save it. 1179 1180int actual_number_of_colors 1181 The number of colors in the color map. 1182 1183Additional decompression parameters that the application may set include: 1184 1185J_DCT_METHOD dct_method 1186 Selects the algorithm used for the DCT step. Choices are the same 1187 as described above for compression. 1188 1189boolean do_fancy_upsampling 1190 If TRUE, use direct DCT scaling with DCT size > 8 for upsampling 1191 of chroma components. 1192 If FALSE, use only DCT size <= 8 and simple separate upsampling. 1193 Default is TRUE. 1194 For better image stability in multiple generation compression cycles 1195 it is preferable that this value matches the corresponding 1196 do_fancy_downsampling value in compression. 1197 1198boolean do_block_smoothing 1199 If TRUE, interblock smoothing is applied in early stages of decoding 1200 progressive JPEG files; if FALSE, not. Default is TRUE. Early 1201 progression stages look "fuzzy" with smoothing, "blocky" without. 1202 In any case, block smoothing ceases to be applied after the first few 1203 AC coefficients are known to full accuracy, so it is relevant only 1204 when using buffered-image mode for progressive images. 1205 1206boolean enable_1pass_quant 1207boolean enable_external_quant 1208boolean enable_2pass_quant 1209 These are significant only in buffered-image mode, which is 1210 described in its own section below. 1211 1212 1213The output image dimensions are given by the following fields. These are 1214computed from the source image dimensions and the decompression parameters 1215by jpeg_start_decompress(). You can also call jpeg_calc_output_dimensions() 1216to obtain the values that will result from the current parameter settings. 1217This can be useful if you are trying to pick a scaling ratio that will get 1218close to a desired target size. It's also important if you are using the 1219JPEG library's memory manager to allocate output buffer space, because you 1220are supposed to request such buffers *before* jpeg_start_decompress(). 1221 1222JDIMENSION output_width Actual dimensions of output image. 1223JDIMENSION output_height 1224int out_color_components Number of color components in out_color_space. 1225int output_components Number of color components returned. 1226int rec_outbuf_height Recommended height of scanline buffer. 1227 1228When quantizing colors, output_components is 1, indicating a single color map 1229index per pixel. Otherwise it equals out_color_components. The output arrays 1230are required to be output_width * output_components JSAMPLEs wide. 1231 1232rec_outbuf_height is the recommended minimum height (in scanlines) of the 1233buffer passed to jpeg_read_scanlines(). If the buffer is smaller, the 1234library will still work, but time will be wasted due to unnecessary data 1235copying. In high-quality modes, rec_outbuf_height is always 1, but some 1236faster, lower-quality modes set it to larger values (typically 2 to 4). 1237If you are going to ask for a high-speed processing mode, you may as well 1238go to the trouble of honoring rec_outbuf_height so as to avoid data copying. 1239(An output buffer larger than rec_outbuf_height lines is OK, but won't 1240provide any material speed improvement over that height.) 1241 1242 1243Special color spaces 1244-------------------- 1245 1246The JPEG standard itself is "color blind" and doesn't specify any particular 1247color space. It is customary to convert color data to a luminance/chrominance 1248color space before compressing, since this permits greater compression. The 1249existing de-facto JPEG file format standards specify YCbCr or grayscale data 1250(JFIF), or grayscale, RGB, YCbCr, CMYK, or YCCK (Adobe). For special 1251applications such as multispectral images, other color spaces can be used, 1252but it must be understood that such files will be unportable. 1253 1254The JPEG library can handle the most common colorspace conversions (namely 1255RGB <=> YCbCr and CMYK <=> YCCK). It can also deal with data of an unknown 1256color space, passing it through without conversion. If you deal extensively 1257with an unusual color space, you can easily extend the library to understand 1258additional color spaces and perform appropriate conversions. 1259 1260For compression, the source data's color space is specified by field 1261in_color_space. This is transformed to the JPEG file's color space given 1262by jpeg_color_space. jpeg_set_defaults() chooses a reasonable JPEG color 1263space depending on in_color_space, but you can override this by calling 1264jpeg_set_colorspace(). Of course you must select a supported transformation. 1265jccolor.c currently supports the following transformations: 1266 RGB => YCbCr 1267 RGB => GRAYSCALE 1268 YCbCr => GRAYSCALE 1269 CMYK => YCCK 1270plus the null transforms: GRAYSCALE => GRAYSCALE, RGB => RGB, 1271YCbCr => YCbCr, CMYK => CMYK, YCCK => YCCK, and UNKNOWN => UNKNOWN. 1272 1273The de-facto file format standards (JFIF and Adobe) specify APPn markers that 1274indicate the color space of the JPEG file. It is important to ensure that 1275these are written correctly, or omitted if the JPEG file's color space is not 1276one of the ones supported by the de-facto standards. jpeg_set_colorspace() 1277will set the compression parameters to include or omit the APPn markers 1278properly, so long as it is told the truth about the JPEG color space. 1279For example, if you are writing some random 3-component color space without 1280conversion, don't try to fake out the library by setting in_color_space and 1281jpeg_color_space to JCS_YCbCr; use JCS_UNKNOWN. You may want to write an 1282APPn marker of your own devising to identify the colorspace --- see "Special 1283markers", below. 1284 1285When told that the color space is UNKNOWN, the library will default to using 1286luminance-quality compression parameters for all color components. You may 1287well want to change these parameters. See the source code for 1288jpeg_set_colorspace(), in jcparam.c, for details. 1289 1290For decompression, the JPEG file's color space is given in jpeg_color_space, 1291and this is transformed to the output color space out_color_space. 1292jpeg_read_header's setting of jpeg_color_space can be relied on if the file 1293conforms to JFIF or Adobe conventions, but otherwise it is no better than a 1294guess. If you know the JPEG file's color space for certain, you can override 1295jpeg_read_header's guess by setting jpeg_color_space. jpeg_read_header also 1296selects a default output color space based on (its guess of) jpeg_color_space; 1297set out_color_space to override this. Again, you must select a supported 1298transformation. jdcolor.c currently supports 1299 YCbCr => GRAYSCALE 1300 YCbCr => RGB 1301 GRAYSCALE => RGB 1302 YCCK => CMYK 1303as well as the null transforms. (Since GRAYSCALE=>RGB is provided, an 1304application can force grayscale JPEGs to look like color JPEGs if it only 1305wants to handle one case.) 1306 1307The two-pass color quantizer, jquant2.c, is specialized to handle RGB data 1308(it weights distances appropriately for RGB colors). You'll need to modify 1309the code if you want to use it for non-RGB output color spaces. Note that 1310jquant2.c is used to map to an application-supplied colormap as well as for 1311the normal two-pass colormap selection process. 1312 1313CAUTION: it appears that Adobe Photoshop writes inverted data in CMYK JPEG 1314files: 0 represents 100% ink coverage, rather than 0% ink as you'd expect. 1315This is arguably a bug in Photoshop, but if you need to work with Photoshop 1316CMYK files, you will have to deal with it in your application. We cannot 1317"fix" this in the library by inverting the data during the CMYK<=>YCCK 1318transform, because that would break other applications, notably Ghostscript. 1319Photoshop versions prior to 3.0 write EPS files containing JPEG-encoded CMYK 1320data in the same inverted-YCCK representation used in bare JPEG files, but 1321the surrounding PostScript code performs an inversion using the PS image 1322operator. I am told that Photoshop 3.0 will write uninverted YCCK in 1323EPS/JPEG files, and will omit the PS-level inversion. (But the data 1324polarity used in bare JPEG files will not change in 3.0.) In either case, 1325the JPEG library must not invert the data itself, or else Ghostscript would 1326read these EPS files incorrectly. 1327 1328 1329Error handling 1330-------------- 1331 1332When the default error handler is used, any error detected inside the JPEG 1333routines will cause a message to be printed on stderr, followed by exit(). 1334You can supply your own error handling routines to override this behavior 1335and to control the treatment of nonfatal warnings and trace/debug messages. 1336The file example.c illustrates the most common case, which is to have the 1337application regain control after an error rather than exiting. 1338 1339The JPEG library never writes any message directly; it always goes through 1340the error handling routines. Three classes of messages are recognized: 1341 * Fatal errors: the library cannot continue. 1342 * Warnings: the library can continue, but the data is corrupt, and a 1343 damaged output image is likely to result. 1344 * Trace/informational messages. These come with a trace level indicating 1345 the importance of the message; you can control the verbosity of the 1346 program by adjusting the maximum trace level that will be displayed. 1347 1348You may, if you wish, simply replace the entire JPEG error handling module 1349(jerror.c) with your own code. However, you can avoid code duplication by 1350only replacing some of the routines depending on the behavior you need. 1351This is accomplished by calling jpeg_std_error() as usual, but then overriding 1352some of the method pointers in the jpeg_error_mgr struct, as illustrated by 1353example.c. 1354 1355All of the error handling routines will receive a pointer to the JPEG object 1356(a j_common_ptr which points to either a jpeg_compress_struct or a 1357jpeg_decompress_struct; if you need to tell which, test the is_decompressor 1358field). This struct includes a pointer to the error manager struct in its 1359"err" field. Frequently, custom error handler routines will need to access 1360additional data which is not known to the JPEG library or the standard error 1361handler. The most convenient way to do this is to embed either the JPEG 1362object or the jpeg_error_mgr struct in a larger structure that contains 1363additional fields; then casting the passed pointer provides access to the 1364additional fields. Again, see example.c for one way to do it. (Beginning 1365with IJG version 6b, there is also a void pointer "client_data" in each 1366JPEG object, which the application can also use to find related data. 1367The library does not touch client_data at all.) 1368 1369The individual methods that you might wish to override are: 1370 1371error_exit (j_common_ptr cinfo) 1372 Receives control for a fatal error. Information sufficient to 1373 generate the error message has been stored in cinfo->err; call 1374 output_message to display it. Control must NOT return to the caller; 1375 generally this routine will exit() or longjmp() somewhere. 1376 Typically you would override this routine to get rid of the exit() 1377 default behavior. Note that if you continue processing, you should 1378 clean up the JPEG object with jpeg_abort() or jpeg_destroy(). 1379 1380output_message (j_common_ptr cinfo) 1381 Actual output of any JPEG message. Override this to send messages 1382 somewhere other than stderr. Note that this method does not know 1383 how to generate a message, only where to send it. 1384 1385format_message (j_common_ptr cinfo, char * buffer) 1386 Constructs a readable error message string based on the error info 1387 stored in cinfo->err. This method is called by output_message. Few 1388 applications should need to override this method. One possible 1389 reason for doing so is to implement dynamic switching of error message 1390 language. 1391 1392emit_message (j_common_ptr cinfo, int msg_level) 1393 Decide whether or not to emit a warning or trace message; if so, 1394 calls output_message. The main reason for overriding this method 1395 would be to abort on warnings. msg_level is -1 for warnings, 1396 0 and up for trace messages. 1397 1398Only error_exit() and emit_message() are called from the rest of the JPEG 1399library; the other two are internal to the error handler. 1400 1401The actual message texts are stored in an array of strings which is pointed to 1402by the field err->jpeg_message_table. The messages are numbered from 0 to 1403err->last_jpeg_message, and it is these code numbers that are used in the 1404JPEG library code. You could replace the message texts (for instance, with 1405messages in French or German) by changing the message table pointer. See 1406jerror.h for the default texts. CAUTION: this table will almost certainly 1407change or grow from one library version to the next. 1408 1409It may be useful for an application to add its own message texts that are 1410handled by the same mechanism. The error handler supports a second "add-on" 1411message table for this purpose. To define an addon table, set the pointer 1412err->addon_message_table and the message numbers err->first_addon_message and 1413err->last_addon_message. If you number the addon messages beginning at 1000 1414or so, you won't have to worry about conflicts with the library's built-in 1415messages. See the sample applications cjpeg/djpeg for an example of using 1416addon messages (the addon messages are defined in cderror.h). 1417 1418Actual invocation of the error handler is done via macros defined in jerror.h: 1419 ERREXITn(...) for fatal errors 1420 WARNMSn(...) for corrupt-data warnings 1421 TRACEMSn(...) for trace and informational messages. 1422These macros store the message code and any additional parameters into the 1423error handler struct, then invoke the error_exit() or emit_message() method. 1424The variants of each macro are for varying numbers of additional parameters. 1425The additional parameters are inserted into the generated message using 1426standard printf() format codes. 1427 1428See jerror.h and jerror.c for further details. 1429 1430 1431Compressed data handling (source and destination managers) 1432---------------------------------------------------------- 1433 1434The JPEG compression library sends its compressed data to a "destination 1435manager" module. The default destination manager just writes the data to a 1436memory buffer or to a stdio stream, but you can provide your own manager to 1437do something else. Similarly, the decompression library calls a "source 1438manager" to obtain the compressed data; you can provide your own source 1439manager if you want the data to come from somewhere other than a memory 1440buffer or a stdio stream. 1441 1442In both cases, compressed data is processed a bufferload at a time: the 1443destination or source manager provides a work buffer, and the library invokes 1444the manager only when the buffer is filled or emptied. (You could define a 1445one-character buffer to force the manager to be invoked for each byte, but 1446that would be rather inefficient.) The buffer's size and location are 1447controlled by the manager, not by the library. For example, the memory 1448source manager just makes the buffer pointer and length point to the original 1449data in memory. In this case the buffer-reload procedure will be invoked 1450only if the decompressor ran off the end of the datastream, which would 1451indicate an erroneous datastream. 1452 1453The work buffer is defined as an array of datatype JOCTET, which is generally 1454"char" or "unsigned char". On a machine where char is not exactly 8 bits 1455wide, you must define JOCTET as a wider data type and then modify the data 1456source and destination modules to transcribe the work arrays into 8-bit units 1457on external storage. 1458 1459A data destination manager struct contains a pointer and count defining the 1460next byte to write in the work buffer and the remaining free space: 1461 1462 JOCTET * next_output_byte; /* => next byte to write in buffer */ 1463 size_t free_in_buffer; /* # of byte spaces remaining in buffer */ 1464 1465The library increments the pointer and decrements the count until the buffer 1466is filled. The manager's empty_output_buffer method must reset the pointer 1467and count. The manager is expected to remember the buffer's starting address 1468and total size in private fields not visible to the library. 1469 1470A data destination manager provides three methods: 1471 1472init_destination (j_compress_ptr cinfo) 1473 Initialize destination. This is called by jpeg_start_compress() 1474 before any data is actually written. It must initialize 1475 next_output_byte and free_in_buffer. free_in_buffer must be 1476 initialized to a positive value. 1477 1478empty_output_buffer (j_compress_ptr cinfo) 1479 This is called whenever the buffer has filled (free_in_buffer 1480 reaches zero). In typical applications, it should write out the 1481 *entire* buffer (use the saved start address and buffer length; 1482 ignore the current state of next_output_byte and free_in_buffer). 1483 Then reset the pointer & count to the start of the buffer, and 1484 return TRUE indicating that the buffer has been dumped. 1485 free_in_buffer must be set to a positive value when TRUE is 1486 returned. A FALSE return should only be used when I/O suspension is 1487 desired (this operating mode is discussed in the next section). 1488 1489term_destination (j_compress_ptr cinfo) 1490 Terminate destination --- called by jpeg_finish_compress() after all 1491 data has been written. In most applications, this must flush any 1492 data remaining in the buffer. Use either next_output_byte or 1493 free_in_buffer to determine how much data is in the buffer. 1494 1495term_destination() is NOT called by jpeg_abort() or jpeg_destroy(). If you 1496want the destination manager to be cleaned up during an abort, you must do it 1497yourself. 1498 1499You will also need code to create a jpeg_destination_mgr struct, fill in its 1500method pointers, and insert a pointer to the struct into the "dest" field of 1501the JPEG compression object. This can be done in-line in your setup code if 1502you like, but it's probably cleaner to provide a separate routine similar to 1503the jpeg_stdio_dest() or jpeg_mem_dest() routines of the supplied destination 1504managers. 1505 1506Decompression source managers follow a parallel design, but with some 1507additional frammishes. The source manager struct contains a pointer and count 1508defining the next byte to read from the work buffer and the number of bytes 1509remaining: 1510 1511 const JOCTET * next_input_byte; /* => next byte to read from buffer */ 1512 size_t bytes_in_buffer; /* # of bytes remaining in buffer */ 1513 1514The library increments the pointer and decrements the count until the buffer 1515is emptied. The manager's fill_input_buffer method must reset the pointer and 1516count. In most applications, the manager must remember the buffer's starting 1517address and total size in private fields not visible to the library. 1518 1519A data source manager provides five methods: 1520 1521init_source (j_decompress_ptr cinfo) 1522 Initialize source. This is called by jpeg_read_header() before any 1523 data is actually read. Unlike init_destination(), it may leave 1524 bytes_in_buffer set to 0 (in which case a fill_input_buffer() call 1525 will occur immediately). 1526 1527fill_input_buffer (j_decompress_ptr cinfo) 1528 This is called whenever bytes_in_buffer has reached zero and more 1529 data is wanted. In typical applications, it should read fresh data 1530 into the buffer (ignoring the current state of next_input_byte and 1531 bytes_in_buffer), reset the pointer & count to the start of the 1532 buffer, and return TRUE indicating that the buffer has been reloaded. 1533 It is not necessary to fill the buffer entirely, only to obtain at 1534 least one more byte. bytes_in_buffer MUST be set to a positive value 1535 if TRUE is returned. A FALSE return should only be used when I/O 1536 suspension is desired (this mode is discussed in the next section). 1537 1538skip_input_data (j_decompress_ptr cinfo, long num_bytes) 1539 Skip num_bytes worth of data. The buffer pointer and count should 1540 be advanced over num_bytes input bytes, refilling the buffer as 1541 needed. This is used to skip over a potentially large amount of 1542 uninteresting data (such as an APPn marker). In some applications 1543 it may be possible to optimize away the reading of the skipped data, 1544 but it's not clear that being smart is worth much trouble; large 1545 skips are uncommon. bytes_in_buffer may be zero on return. 1546 A zero or negative skip count should be treated as a no-op. 1547 1548resync_to_restart (j_decompress_ptr cinfo, int desired) 1549 This routine is called only when the decompressor has failed to find 1550 a restart (RSTn) marker where one is expected. Its mission is to 1551 find a suitable point for resuming decompression. For most 1552 applications, we recommend that you just use the default resync 1553 procedure, jpeg_resync_to_restart(). However, if you are able to back 1554 up in the input data stream, or if you have a-priori knowledge about 1555 the likely location of restart markers, you may be able to do better. 1556 Read the read_restart_marker() and jpeg_resync_to_restart() routines 1557 in jdmarker.c if you think you'd like to implement your own resync 1558 procedure. 1559 1560term_source (j_decompress_ptr cinfo) 1561 Terminate source --- called by jpeg_finish_decompress() after all 1562 data has been read. Often a no-op. 1563 1564For both fill_input_buffer() and skip_input_data(), there is no such thing 1565as an EOF return. If the end of the file has been reached, the routine has 1566a choice of exiting via ERREXIT() or inserting fake data into the buffer. 1567In most cases, generating a warning message and inserting a fake EOI marker 1568is the best course of action --- this will allow the decompressor to output 1569however much of the image is there. In pathological cases, the decompressor 1570may swallow the EOI and again demand data ... just keep feeding it fake EOIs. 1571jdatasrc.c illustrates the recommended error recovery behavior. 1572 1573term_source() is NOT called by jpeg_abort() or jpeg_destroy(). If you want 1574the source manager to be cleaned up during an abort, you must do it yourself. 1575 1576You will also need code to create a jpeg_source_mgr struct, fill in its method 1577pointers, and insert a pointer to the struct into the "src" field of the JPEG 1578decompression object. This can be done in-line in your setup code if you 1579like, but it's probably cleaner to provide a separate routine similar to the 1580jpeg_stdio_src() or jpeg_mem_src() routines of the supplied source managers. 1581 1582For more information, consult the memory and stdio source and destination 1583managers in jdatasrc.c and jdatadst.c. 1584 1585 1586I/O suspension 1587-------------- 1588 1589Some applications need to use the JPEG library as an incremental memory-to- 1590memory filter: when the compressed data buffer is filled or emptied, they want 1591control to return to the outer loop, rather than expecting that the buffer can 1592be emptied or reloaded within the data source/destination manager subroutine. 1593The library supports this need by providing an "I/O suspension" mode, which we 1594describe in this section. 1595 1596The I/O suspension mode is not a panacea: nothing is guaranteed about the 1597maximum amount of time spent in any one call to the library, so it will not 1598eliminate response-time problems in single-threaded applications. If you 1599need guaranteed response time, we suggest you "bite the bullet" and implement 1600a real multi-tasking capability. 1601 1602To use I/O suspension, cooperation is needed between the calling application 1603and the data source or destination manager; you will always need a custom 1604source/destination manager. (Please read the previous section if you haven't 1605already.) The basic idea is that the empty_output_buffer() or 1606fill_input_buffer() routine is a no-op, merely returning FALSE to indicate 1607that it has done nothing. Upon seeing this, the JPEG library suspends 1608operation and returns to its caller. The surrounding application is 1609responsible for emptying or refilling the work buffer before calling the 1610JPEG library again. 1611 1612Compression suspension: 1613 1614For compression suspension, use an empty_output_buffer() routine that returns 1615FALSE; typically it will not do anything else. This will cause the 1616compressor to return to the caller of jpeg_write_scanlines(), with the return 1617value indicating that not all the supplied scanlines have been accepted. 1618The application must make more room in the output buffer, adjust the output 1619buffer pointer/count appropriately, and then call jpeg_write_scanlines() 1620again, pointing to the first unconsumed scanline. 1621 1622When forced to suspend, the compressor will backtrack to a convenient stopping 1623point (usually the start of the current MCU); it will regenerate some output 1624data when restarted. Therefore, although empty_output_buffer() is only 1625called when the buffer is filled, you should NOT write out the entire buffer 1626after a suspension. Write only the data up to the current position of 1627next_output_byte/free_in_buffer. The data beyond that point will be 1628regenerated after resumption. 1629 1630Because of the backtracking behavior, a good-size output buffer is essential 1631for efficiency; you don't want the compressor to suspend often. (In fact, an 1632overly small buffer could lead to infinite looping, if a single MCU required 1633more data than would fit in the buffer.) We recommend a buffer of at least 1634several Kbytes. You may want to insert explicit code to ensure that you don't 1635call jpeg_write_scanlines() unless there is a reasonable amount of space in 1636the output buffer; in other words, flush the buffer before trying to compress 1637more data. 1638 1639The compressor does not allow suspension while it is trying to write JPEG 1640markers at the beginning and end of the file. This means that: 1641 * At the beginning of a compression operation, there must be enough free 1642 space in the output buffer to hold the header markers (typically 600 or 1643 so bytes). The recommended buffer size is bigger than this anyway, so 1644 this is not a problem as long as you start with an empty buffer. However, 1645 this restriction might catch you if you insert large special markers, such 1646 as a JFIF thumbnail image, without flushing the buffer afterwards. 1647 * When you call jpeg_finish_compress(), there must be enough space in the 1648 output buffer to emit any buffered data and the final EOI marker. In the 1649 current implementation, half a dozen bytes should suffice for this, but 1650 for safety's sake we recommend ensuring that at least 100 bytes are free 1651 before calling jpeg_finish_compress(). 1652 1653A more significant restriction is that jpeg_finish_compress() cannot suspend. 1654This means you cannot use suspension with multi-pass operating modes, namely 1655Huffman code optimization and multiple-scan output. Those modes write the 1656whole file during jpeg_finish_compress(), which will certainly result in 1657buffer overrun. (Note that this restriction applies only to compression, 1658not decompression. The decompressor supports input suspension in all of its 1659operating modes.) 1660 1661Decompression suspension: 1662 1663For decompression suspension, use a fill_input_buffer() routine that simply 1664returns FALSE (except perhaps during error recovery, as discussed below). 1665This will cause the decompressor to return to its caller with an indication 1666that suspension has occurred. This can happen at four places: 1667 * jpeg_read_header(): will return JPEG_SUSPENDED. 1668 * jpeg_start_decompress(): will return FALSE, rather than its usual TRUE. 1669 * jpeg_read_scanlines(): will return the number of scanlines already 1670 completed (possibly 0). 1671 * jpeg_finish_decompress(): will return FALSE, rather than its usual TRUE. 1672The surrounding application must recognize these cases, load more data into 1673the input buffer, and repeat the call. In the case of jpeg_read_scanlines(), 1674increment the passed pointers past any scanlines successfully read. 1675 1676Just as with compression, the decompressor will typically backtrack to a 1677convenient restart point before suspending. When fill_input_buffer() is 1678called, next_input_byte/bytes_in_buffer point to the current restart point, 1679which is where the decompressor will backtrack to if FALSE is returned. 1680The data beyond that position must NOT be discarded if you suspend; it needs 1681to be re-read upon resumption. In most implementations, you'll need to shift 1682this data down to the start of your work buffer and then load more data after 1683it. Again, this behavior means that a several-Kbyte work buffer is essential 1684for decent performance; furthermore, you should load a reasonable amount of 1685new data before resuming decompression. (If you loaded, say, only one new 1686byte each time around, you could waste a LOT of cycles.) 1687 1688The skip_input_data() source manager routine requires special care in a 1689suspension scenario. This routine is NOT granted the ability to suspend the 1690decompressor; it can decrement bytes_in_buffer to zero, but no more. If the 1691requested skip distance exceeds the amount of data currently in the input 1692buffer, then skip_input_data() must set bytes_in_buffer to zero and record the 1693additional skip distance somewhere else. The decompressor will immediately 1694call fill_input_buffer(), which should return FALSE, which will cause a 1695suspension return. The surrounding application must then arrange to discard 1696the recorded number of bytes before it resumes loading the input buffer. 1697(Yes, this design is rather baroque, but it avoids complexity in the far more 1698common case where a non-suspending source manager is used.) 1699 1700If the input data has been exhausted, we recommend that you emit a warning 1701and insert dummy EOI markers just as a non-suspending data source manager 1702would do. This can be handled either in the surrounding application logic or 1703within fill_input_buffer(); the latter is probably more efficient. If 1704fill_input_buffer() knows that no more data is available, it can set the 1705pointer/count to point to a dummy EOI marker and then return TRUE just as 1706though it had read more data in a non-suspending situation. 1707 1708The decompressor does not attempt to suspend within standard JPEG markers; 1709instead it will backtrack to the start of the marker and reprocess the whole 1710marker next time. Hence the input buffer must be large enough to hold the 1711longest standard marker in the file. Standard JPEG markers should normally 1712not exceed a few hundred bytes each (DHT tables are typically the longest). 1713We recommend at least a 2K buffer for performance reasons, which is much 1714larger than any correct marker is likely to be. For robustness against 1715damaged marker length counts, you may wish to insert a test in your 1716application for the case that the input buffer is completely full and yet 1717the decoder has suspended without consuming any data --- otherwise, if this 1718situation did occur, it would lead to an endless loop. (The library can't 1719provide this test since it has no idea whether "the buffer is full", or 1720even whether there is a fixed-size input buffer.) 1721 1722The input buffer would need to be 64K to allow for arbitrary COM or APPn 1723markers, but these are handled specially: they are either saved into allocated 1724memory, or skipped over by calling skip_input_data(). In the former case, 1725suspension is handled correctly, and in the latter case, the problem of 1726buffer overrun is placed on skip_input_data's shoulders, as explained above. 1727Note that if you provide your own marker handling routine for large markers, 1728you should consider how to deal with buffer overflow. 1729 1730Multiple-buffer management: 1731 1732In some applications it is desirable to store the compressed data in a linked 1733list of buffer areas, so as to avoid data copying. This can be handled by 1734having empty_output_buffer() or fill_input_buffer() set the pointer and count 1735to reference the next available buffer; FALSE is returned only if no more 1736buffers are available. Although seemingly straightforward, there is a 1737pitfall in this approach: the backtrack that occurs when FALSE is returned 1738could back up into an earlier buffer. For example, when fill_input_buffer() 1739is called, the current pointer & count indicate the backtrack restart point. 1740Since fill_input_buffer() will set the pointer and count to refer to a new 1741buffer, the restart position must be saved somewhere else. Suppose a second 1742call to fill_input_buffer() occurs in the same library call, and no 1743additional input data is available, so fill_input_buffer must return FALSE. 1744If the JPEG library has not moved the pointer/count forward in the current 1745buffer, then *the correct restart point is the saved position in the prior 1746buffer*. Prior buffers may be discarded only after the library establishes 1747a restart point within a later buffer. Similar remarks apply for output into 1748a chain of buffers. 1749 1750The library will never attempt to backtrack over a skip_input_data() call, 1751so any skipped data can be permanently discarded. You still have to deal 1752with the case of skipping not-yet-received data, however. 1753 1754It's much simpler to use only a single buffer; when fill_input_buffer() is 1755called, move any unconsumed data (beyond the current pointer/count) down to 1756the beginning of this buffer and then load new data into the remaining buffer 1757space. This approach requires a little more data copying but is far easier 1758to get right. 1759 1760 1761Progressive JPEG support 1762------------------------ 1763 1764Progressive JPEG rearranges the stored data into a series of scans of 1765increasing quality. In situations where a JPEG file is transmitted across a 1766slow communications link, a decoder can generate a low-quality image very 1767quickly from the first scan, then gradually improve the displayed quality as 1768more scans are received. The final image after all scans are complete is 1769identical to that of a regular (sequential) JPEG file of the same quality 1770setting. Progressive JPEG files are often slightly smaller than equivalent 1771sequential JPEG files, but the possibility of incremental display is the main 1772reason for using progressive JPEG. 1773 1774The IJG encoder library generates progressive JPEG files when given a 1775suitable "scan script" defining how to divide the data into scans. 1776Creation of progressive JPEG files is otherwise transparent to the encoder. 1777Progressive JPEG files can also be read transparently by the decoder library. 1778If the decoding application simply uses the library as defined above, it 1779will receive a final decoded image without any indication that the file was 1780progressive. Of course, this approach does not allow incremental display. 1781To perform incremental display, an application needs to use the decoder 1782library's "buffered-image" mode, in which it receives a decoded image 1783multiple times. 1784 1785Each displayed scan requires about as much work to decode as a full JPEG 1786image of the same size, so the decoder must be fairly fast in relation to the 1787data transmission rate in order to make incremental display useful. However, 1788it is possible to skip displaying the image and simply add the incoming bits 1789to the decoder's coefficient buffer. This is fast because only Huffman 1790decoding need be done, not IDCT, upsampling, colorspace conversion, etc. 1791The IJG decoder library allows the application to switch dynamically between 1792displaying the image and simply absorbing the incoming bits. A properly 1793coded application can automatically adapt the number of display passes to 1794suit the time available as the image is received. Also, a final 1795higher-quality display cycle can be performed from the buffered data after 1796the end of the file is reached. 1797 1798Progressive compression: 1799 1800To create a progressive JPEG file (or a multiple-scan sequential JPEG file), 1801set the scan_info cinfo field to point to an array of scan descriptors, and 1802perform compression as usual. Instead of constructing your own scan list, 1803you can call the jpeg_simple_progression() helper routine to create a 1804recommended progression sequence; this method should be used by all 1805applications that don't want to get involved in the nitty-gritty of 1806progressive scan sequence design. (If you want to provide user control of 1807scan sequences, you may wish to borrow the scan script reading code found 1808in rdswitch.c, so that you can read scan script files just like cjpeg's.) 1809When scan_info is not NULL, the compression library will store DCT'd data 1810into a buffer array as jpeg_write_scanlines() is called, and will emit all 1811the requested scans during jpeg_finish_compress(). This implies that 1812multiple-scan output cannot be created with a suspending data destination 1813manager, since jpeg_finish_compress() does not support suspension. We 1814should also note that the compressor currently forces Huffman optimization 1815mode when creating a progressive JPEG file, because the default Huffman 1816tables are unsuitable for progressive files. 1817 1818Progressive decompression: 1819 1820When buffered-image mode is not used, the decoder library will read all of 1821a multi-scan file during jpeg_start_decompress(), so that it can provide a 1822final decoded image. (Here "multi-scan" means either progressive or 1823multi-scan sequential.) This makes multi-scan files transparent to the 1824decoding application. However, existing applications that used suspending 1825input with version 5 of the IJG library will need to be modified to check 1826for a suspension return from jpeg_start_decompress(). 1827 1828To perform incremental display, an application must use the library's 1829buffered-image mode. This is described in the next section. 1830 1831 1832Buffered-image mode 1833------------------- 1834 1835In buffered-image mode, the library stores the partially decoded image in a 1836coefficient buffer, from which it can be read out as many times as desired. 1837This mode is typically used for incremental display of progressive JPEG files, 1838but it can be used with any JPEG file. Each scan of a progressive JPEG file 1839adds more data (more detail) to the buffered image. The application can 1840display in lockstep with the source file (one display pass per input scan), 1841or it can allow input processing to outrun display processing. By making 1842input and display processing run independently, it is possible for the 1843application to adapt progressive display to a wide range of data transmission 1844rates. 1845 1846The basic control flow for buffered-image decoding is 1847 1848 jpeg_create_decompress() 1849 set data source 1850 jpeg_read_header() 1851 set overall decompression parameters 1852 cinfo.buffered_image = TRUE; /* select buffered-image mode */ 1853 jpeg_start_decompress() 1854 for (each output pass) { 1855 adjust output decompression parameters if required 1856 jpeg_start_output() /* start a new output pass */ 1857 for (all scanlines in image) { 1858 jpeg_read_scanlines() 1859 display scanlines 1860 } 1861 jpeg_finish_output() /* terminate output pass */ 1862 } 1863 jpeg_finish_decompress() 1864 jpeg_destroy_decompress() 1865 1866This differs from ordinary unbuffered decoding in that there is an additional 1867level of looping. The application can choose how many output passes to make 1868and how to display each pass. 1869 1870The simplest approach to displaying progressive images is to do one display 1871pass for each scan appearing in the input file. In this case the outer loop 1872condition is typically 1873 while (! jpeg_input_complete(&cinfo)) 1874and the start-output call should read 1875 jpeg_start_output(&cinfo, cinfo.input_scan_number); 1876The second parameter to jpeg_start_output() indicates which scan of the input 1877file is to be displayed; the scans are numbered starting at 1 for this 1878purpose. (You can use a loop counter starting at 1 if you like, but using 1879the library's input scan counter is easier.) The library automatically reads 1880data as necessary to complete each requested scan, and jpeg_finish_output() 1881advances to the next scan or end-of-image marker (hence input_scan_number 1882will be incremented by the time control arrives back at jpeg_start_output()). 1883With this technique, data is read from the input file only as needed, and 1884input and output processing run in lockstep. 1885 1886After reading the final scan and reaching the end of the input file, the 1887buffered image remains available; it can be read additional times by 1888repeating the jpeg_start_output()/jpeg_read_scanlines()/jpeg_finish_output() 1889sequence. For example, a useful technique is to use fast one-pass color 1890quantization for display passes made while the image is arriving, followed by 1891a final display pass using two-pass quantization for highest quality. This 1892is done by changing the library parameters before the final output pass. 1893Changing parameters between passes is discussed in detail below. 1894 1895In general the last scan of a progressive file cannot be recognized as such 1896until after it is read, so a post-input display pass is the best approach if 1897you want special processing in the final pass. 1898 1899When done with the image, be sure to call jpeg_finish_decompress() to release 1900the buffered image (or just use jpeg_destroy_decompress()). 1901 1902If input data arrives faster than it can be displayed, the application can 1903cause the library to decode input data in advance of what's needed to produce 1904output. This is done by calling the routine jpeg_consume_input(). 1905The return value is one of the following: 1906 JPEG_REACHED_SOS: reached an SOS marker (the start of a new scan) 1907 JPEG_REACHED_EOI: reached the EOI marker (end of image) 1908 JPEG_ROW_COMPLETED: completed reading one MCU row of compressed data 1909 JPEG_SCAN_COMPLETED: completed reading last MCU row of current scan 1910 JPEG_SUSPENDED: suspended before completing any of the above 1911(JPEG_SUSPENDED can occur only if a suspending data source is used.) This 1912routine can be called at any time after initializing the JPEG object. It 1913reads some additional data and returns when one of the indicated significant 1914events occurs. (If called after the EOI marker is reached, it will 1915immediately return JPEG_REACHED_EOI without attempting to read more data.) 1916 1917The library's output processing will automatically call jpeg_consume_input() 1918whenever the output processing overtakes the input; thus, simple lockstep 1919display requires no direct calls to jpeg_consume_input(). But by adding 1920calls to jpeg_consume_input(), you can absorb data in advance of what is 1921being displayed. This has two benefits: 1922 * You can limit buildup of unprocessed data in your input buffer. 1923 * You can eliminate extra display passes by paying attention to the 1924 state of the library's input processing. 1925 1926The first of these benefits only requires interspersing calls to 1927jpeg_consume_input() with your display operations and any other processing 1928you may be doing. To avoid wasting cycles due to backtracking, it's best to 1929call jpeg_consume_input() only after a hundred or so new bytes have arrived. 1930This is discussed further under "I/O suspension", above. (Note: the JPEG 1931library currently is not thread-safe. You must not call jpeg_consume_input() 1932from one thread of control if a different library routine is working on the 1933same JPEG object in another thread.) 1934 1935When input arrives fast enough that more than one new scan is available 1936before you start a new output pass, you may as well skip the output pass 1937corresponding to the completed scan. This occurs for free if you pass 1938cinfo.input_scan_number as the target scan number to jpeg_start_output(). 1939The input_scan_number field is simply the index of the scan currently being 1940consumed by the input processor. You can ensure that this is up-to-date by 1941emptying the input buffer just before calling jpeg_start_output(): call 1942jpeg_consume_input() repeatedly until it returns JPEG_SUSPENDED or 1943JPEG_REACHED_EOI. 1944 1945The target scan number passed to jpeg_start_output() is saved in the 1946cinfo.output_scan_number field. The library's output processing calls 1947jpeg_consume_input() whenever the current input scan number and row within 1948that scan is less than or equal to the current output scan number and row. 1949Thus, input processing can "get ahead" of the output processing but is not 1950allowed to "fall behind". You can achieve several different effects by 1951manipulating this interlock rule. For example, if you pass a target scan 1952number greater than the current input scan number, the output processor will 1953wait until that scan starts to arrive before producing any output. (To avoid 1954an infinite loop, the target scan number is automatically reset to the last 1955scan number when the end of image is reached. Thus, if you specify a large 1956target scan number, the library will just absorb the entire input file and 1957then perform an output pass. This is effectively the same as what 1958jpeg_start_decompress() does when you don't select buffered-image mode.) 1959When you pass a target scan number equal to the current input scan number, 1960the image is displayed no faster than the current input scan arrives. The 1961final possibility is to pass a target scan number less than the current input 1962scan number; this disables the input/output interlock and causes the output 1963processor to simply display whatever it finds in the image buffer, without 1964waiting for input. (However, the library will not accept a target scan 1965number less than one, so you can't avoid waiting for the first scan.) 1966 1967When data is arriving faster than the output display processing can advance 1968through the image, jpeg_consume_input() will store data into the buffered 1969image beyond the point at which the output processing is reading data out 1970again. If the input arrives fast enough, it may "wrap around" the buffer to 1971the point where the input is more than one whole scan ahead of the output. 1972If the output processing simply proceeds through its display pass without 1973paying attention to the input, the effect seen on-screen is that the lower 1974part of the image is one or more scans better in quality than the upper part. 1975Then, when the next output scan is started, you have a choice of what target 1976scan number to use. The recommended choice is to use the current input scan 1977number at that time, which implies that you've skipped the output scans 1978corresponding to the input scans that were completed while you processed the 1979previous output scan. In this way, the decoder automatically adapts its 1980speed to the arriving data, by skipping output scans as necessary to keep up 1981with the arriving data. 1982 1983When using this strategy, you'll want to be sure that you perform a final 1984output pass after receiving all the data; otherwise your last display may not 1985be full quality across the whole screen. So the right outer loop logic is 1986something like this: 1987 do { 1988 absorb any waiting input by calling jpeg_consume_input() 1989 final_pass = jpeg_input_complete(&cinfo); 1990 adjust output decompression parameters if required 1991 jpeg_start_output(&cinfo, cinfo.input_scan_number); 1992 ... 1993 jpeg_finish_output() 1994 } while (! final_pass); 1995rather than quitting as soon as jpeg_input_complete() returns TRUE. This 1996arrangement makes it simple to use higher-quality decoding parameters 1997for the final pass. But if you don't want to use special parameters for 1998the final pass, the right loop logic is like this: 1999 for (;;) { 2000 absorb any waiting input by calling jpeg_consume_input() 2001 jpeg_start_output(&cinfo, cinfo.input_scan_number); 2002 ... 2003 jpeg_finish_output() 2004 if (jpeg_input_complete(&cinfo) && 2005 cinfo.input_scan_number == cinfo.output_scan_number) 2006 break; 2007 } 2008In this case you don't need to know in advance whether an output pass is to 2009be the last one, so it's not necessary to have reached EOF before starting 2010the final output pass; rather, what you want to test is whether the output 2011pass was performed in sync with the final input scan. This form of the loop 2012will avoid an extra output pass whenever the decoder is able (or nearly able) 2013to keep up with the incoming data. 2014 2015When the data transmission speed is high, you might begin a display pass, 2016then find that much or all of the file has arrived before you can complete 2017the pass. (You can detect this by noting the JPEG_REACHED_EOI return code 2018from jpeg_consume_input(), or equivalently by testing jpeg_input_complete().) 2019In this situation you may wish to abort the current display pass and start a 2020new one using the newly arrived information. To do so, just call 2021jpeg_finish_output() and then start a new pass with jpeg_start_output(). 2022 2023A variant strategy is to abort and restart display if more than one complete 2024scan arrives during an output pass; this can be detected by noting 2025JPEG_REACHED_SOS returns and/or examining cinfo.input_scan_number. This 2026idea should be employed with caution, however, since the display process 2027might never get to the bottom of the image before being aborted, resulting 2028in the lower part of the screen being several passes worse than the upper. 2029In most cases it's probably best to abort an output pass only if the whole 2030file has arrived and you want to begin the final output pass immediately. 2031 2032When receiving data across a communication link, we recommend always using 2033the current input scan number for the output target scan number; if a 2034higher-quality final pass is to be done, it should be started (aborting any 2035incomplete output pass) as soon as the end of file is received. However, 2036many other strategies are possible. For example, the application can examine 2037the parameters of the current input scan and decide whether to display it or 2038not. If the scan contains only chroma data, one might choose not to use it 2039as the target scan, expecting that the scan will be small and will arrive 2040quickly. To skip to the next scan, call jpeg_consume_input() until it 2041returns JPEG_REACHED_SOS or JPEG_REACHED_EOI. Or just use the next higher 2042number as the target scan for jpeg_start_output(); but that method doesn't 2043let you inspect the next scan's parameters before deciding to display it. 2044 2045 2046In buffered-image mode, jpeg_start_decompress() never performs input and 2047thus never suspends. An application that uses input suspension with 2048buffered-image mode must be prepared for suspension returns from these 2049routines: 2050* jpeg_start_output() performs input only if you request 2-pass quantization 2051 and the target scan isn't fully read yet. (This is discussed below.) 2052* jpeg_read_scanlines(), as always, returns the number of scanlines that it 2053 was able to produce before suspending. 2054* jpeg_finish_output() will read any markers following the target scan, 2055 up to the end of the file or the SOS marker that begins another scan. 2056 (But it reads no input if jpeg_consume_input() has already reached the 2057 end of the file or a SOS marker beyond the target output scan.) 2058* jpeg_finish_decompress() will read until the end of file, and thus can 2059 suspend if the end hasn't already been reached (as can be tested by 2060 calling jpeg_input_complete()). 2061jpeg_start_output(), jpeg_finish_output(), and jpeg_finish_decompress() 2062all return TRUE if they completed their tasks, FALSE if they had to suspend. 2063In the event of a FALSE return, the application must load more input data 2064and repeat the call. Applications that use non-suspending data sources need 2065not check the return values of these three routines. 2066 2067 2068It is possible to change decoding parameters between output passes in the 2069buffered-image mode. The decoder library currently supports only very 2070limited changes of parameters. ONLY THE FOLLOWING parameter changes are 2071allowed after jpeg_start_decompress() is called: 2072* dct_method can be changed before each call to jpeg_start_output(). 2073 For example, one could use a fast DCT method for early scans, changing 2074 to a higher quality method for the final scan. 2075* dither_mode can be changed before each call to jpeg_start_output(); 2076 of course this has no impact if not using color quantization. Typically 2077 one would use ordered dither for initial passes, then switch to 2078 Floyd-Steinberg dither for the final pass. Caution: changing dither mode 2079 can cause more memory to be allocated by the library. Although the amount 2080 of memory involved is not large (a scanline or so), it may cause the 2081 initial max_memory_to_use specification to be exceeded, which in the worst 2082 case would result in an out-of-memory failure. 2083* do_block_smoothing can be changed before each call to jpeg_start_output(). 2084 This setting is relevant only when decoding a progressive JPEG image. 2085 During the first DC-only scan, block smoothing provides a very "fuzzy" look 2086 instead of the very "blocky" look seen without it; which is better seems a 2087 matter of personal taste. But block smoothing is nearly always a win 2088 during later stages, especially when decoding a successive-approximation 2089 image: smoothing helps to hide the slight blockiness that otherwise shows 2090 up on smooth gradients until the lowest coefficient bits are sent. 2091* Color quantization mode can be changed under the rules described below. 2092 You *cannot* change between full-color and quantized output (because that 2093 would alter the required I/O buffer sizes), but you can change which 2094 quantization method is used. 2095 2096When generating color-quantized output, changing quantization method is a 2097very useful way of switching between high-speed and high-quality display. 2098The library allows you to change among its three quantization methods: 20991. Single-pass quantization to a fixed color cube. 2100 Selected by cinfo.two_pass_quantize = FALSE and cinfo.colormap = NULL. 21012. Single-pass quantization to an application-supplied colormap. 2102 Selected by setting cinfo.colormap to point to the colormap (the value of 2103 two_pass_quantize is ignored); also set cinfo.actual_number_of_colors. 21043. Two-pass quantization to a colormap chosen specifically for the image. 2105 Selected by cinfo.two_pass_quantize = TRUE and cinfo.colormap = NULL. 2106 (This is the default setting selected by jpeg_read_header, but it is 2107 probably NOT what you want for the first pass of progressive display!) 2108These methods offer successively better quality and lesser speed. However, 2109only the first method is available for quantizing in non-RGB color spaces. 2110 2111IMPORTANT: because the different quantizer methods have very different 2112working-storage requirements, the library requires you to indicate which 2113one(s) you intend to use before you call jpeg_start_decompress(). (If we did 2114not require this, the max_memory_to_use setting would be a complete fiction.) 2115You do this by setting one or more of these three cinfo fields to TRUE: 2116 enable_1pass_quant Fixed color cube colormap 2117 enable_external_quant Externally-supplied colormap 2118 enable_2pass_quant Two-pass custom colormap 2119All three are initialized FALSE by jpeg_read_header(). But 2120jpeg_start_decompress() automatically sets TRUE the one selected by the 2121current two_pass_quantize and colormap settings, so you only need to set the 2122enable flags for any other quantization methods you plan to change to later. 2123 2124After setting the enable flags correctly at jpeg_start_decompress() time, you 2125can change to any enabled quantization method by setting two_pass_quantize 2126and colormap properly just before calling jpeg_start_output(). The following 2127special rules apply: 21281. You must explicitly set cinfo.colormap to NULL when switching to 1-pass 2129 or 2-pass mode from a different mode, or when you want the 2-pass 2130 quantizer to be re-run to generate a new colormap. 21312. To switch to an external colormap, or to change to a different external 2132 colormap than was used on the prior pass, you must call 2133 jpeg_new_colormap() after setting cinfo.colormap. 2134NOTE: if you want to use the same colormap as was used in the prior pass, 2135you should not do either of these things. This will save some nontrivial 2136switchover costs. 2137(These requirements exist because cinfo.colormap will always be non-NULL 2138after completing a prior output pass, since both the 1-pass and 2-pass 2139quantizers set it to point to their output colormaps. Thus you have to 2140do one of these two things to notify the library that something has changed. 2141Yup, it's a bit klugy, but it's necessary to do it this way for backwards 2142compatibility.) 2143 2144Note that in buffered-image mode, the library generates any requested colormap 2145during jpeg_start_output(), not during jpeg_start_decompress(). 2146 2147When using two-pass quantization, jpeg_start_output() makes a pass over the 2148buffered image to determine the optimum color map; it therefore may take a 2149significant amount of time, whereas ordinarily it does little work. The 2150progress monitor hook is called during this pass, if defined. It is also 2151important to realize that if the specified target scan number is greater than 2152or equal to the current input scan number, jpeg_start_output() will attempt 2153to consume input as it makes this pass. If you use a suspending data source, 2154you need to check for a FALSE return from jpeg_start_output() under these 2155conditions. The combination of 2-pass quantization and a not-yet-fully-read 2156target scan is the only case in which jpeg_start_output() will consume input. 2157 2158 2159Application authors who support buffered-image mode may be tempted to use it 2160for all JPEG images, even single-scan ones. This will work, but it is 2161inefficient: there is no need to create an image-sized coefficient buffer for 2162single-scan images. Requesting buffered-image mode for such an image wastes 2163memory. Worse, it can cost time on large images, since the buffered data has 2164to be swapped out or written to a temporary file. If you are concerned about 2165maximum performance on baseline JPEG files, you should use buffered-image 2166mode only when the incoming file actually has multiple scans. This can be 2167tested by calling jpeg_has_multiple_scans(), which will return a correct 2168result at any time after jpeg_read_header() completes. 2169 2170It is also worth noting that when you use jpeg_consume_input() to let input 2171processing get ahead of output processing, the resulting pattern of access to 2172the coefficient buffer is quite nonsequential. It's best to use the memory 2173manager jmemnobs.c if you can (ie, if you have enough real or virtual main 2174memory). If not, at least make sure that max_memory_to_use is set as high as 2175possible. If the JPEG memory manager has to use a temporary file, you will 2176probably see a lot of disk traffic and poor performance. (This could be 2177improved with additional work on the memory manager, but we haven't gotten 2178around to it yet.) 2179 2180In some applications it may be convenient to use jpeg_consume_input() for all 2181input processing, including reading the initial markers; that is, you may 2182wish to call jpeg_consume_input() instead of jpeg_read_header() during 2183startup. This works, but note that you must check for JPEG_REACHED_SOS and 2184JPEG_REACHED_EOI return codes as the equivalent of jpeg_read_header's codes. 2185Once the first SOS marker has been reached, you must call 2186jpeg_start_decompress() before jpeg_consume_input() will consume more input; 2187it'll just keep returning JPEG_REACHED_SOS until you do. If you read a 2188tables-only file this way, jpeg_consume_input() will return JPEG_REACHED_EOI 2189without ever returning JPEG_REACHED_SOS; be sure to check for this case. 2190If this happens, the decompressor will not read any more input until you call 2191jpeg_abort() to reset it. It is OK to call jpeg_consume_input() even when not 2192using buffered-image mode, but in that case it's basically a no-op after the 2193initial markers have been read: it will just return JPEG_SUSPENDED. 2194 2195 2196Abbreviated datastreams and multiple images 2197------------------------------------------- 2198 2199A JPEG compression or decompression object can be reused to process multiple 2200images. This saves a small amount of time per image by eliminating the 2201"create" and "destroy" operations, but that isn't the real purpose of the 2202feature. Rather, reuse of an object provides support for abbreviated JPEG 2203datastreams. Object reuse can also simplify processing a series of images in 2204a single input or output file. This section explains these features. 2205 2206A JPEG file normally contains several hundred bytes worth of quantization 2207and Huffman tables. In a situation where many images will be stored or 2208transmitted with identical tables, this may represent an annoying overhead. 2209The JPEG standard therefore permits tables to be omitted. The standard 2210defines three classes of JPEG datastreams: 2211 * "Interchange" datastreams contain an image and all tables needed to decode 2212 the image. These are the usual kind of JPEG file. 2213 * "Abbreviated image" datastreams contain an image, but are missing some or 2214 all of the tables needed to decode that image. 2215 * "Abbreviated table specification" (henceforth "tables-only") datastreams 2216 contain only table specifications. 2217To decode an abbreviated image, it is necessary to load the missing table(s) 2218into the decoder beforehand. This can be accomplished by reading a separate 2219tables-only file. A variant scheme uses a series of images in which the first 2220image is an interchange (complete) datastream, while subsequent ones are 2221abbreviated and rely on the tables loaded by the first image. It is assumed 2222that once the decoder has read a table, it will remember that table until a 2223new definition for the same table number is encountered. 2224 2225It is the application designer's responsibility to figure out how to associate 2226the correct tables with an abbreviated image. While abbreviated datastreams 2227can be useful in a closed environment, their use is strongly discouraged in 2228any situation where data exchange with other applications might be needed. 2229Caveat designer. 2230 2231The JPEG library provides support for reading and writing any combination of 2232tables-only datastreams and abbreviated images. In both compression and 2233decompression objects, a quantization or Huffman table will be retained for 2234the lifetime of the object, unless it is overwritten by a new table definition. 2235 2236 2237To create abbreviated image datastreams, it is only necessary to tell the 2238compressor not to emit some or all of the tables it is using. Each 2239quantization and Huffman table struct contains a boolean field "sent_table", 2240which normally is initialized to FALSE. For each table used by the image, the 2241header-writing process emits the table and sets sent_table = TRUE unless it is 2242already TRUE. (In normal usage, this prevents outputting the same table 2243definition multiple times, as would otherwise occur because the chroma 2244components typically share tables.) Thus, setting this field to TRUE before 2245calling jpeg_start_compress() will prevent the table from being written at 2246all. 2247 2248If you want to create a "pure" abbreviated image file containing no tables, 2249just call "jpeg_suppress_tables(&cinfo, TRUE)" after constructing all the 2250tables. If you want to emit some but not all tables, you'll need to set the 2251individual sent_table fields directly. 2252 2253To create an abbreviated image, you must also call jpeg_start_compress() 2254with a second parameter of FALSE, not TRUE. Otherwise jpeg_start_compress() 2255will force all the sent_table fields to FALSE. (This is a safety feature to 2256prevent abbreviated images from being created accidentally.) 2257 2258To create a tables-only file, perform the same parameter setup that you 2259normally would, but instead of calling jpeg_start_compress() and so on, call 2260jpeg_write_tables(&cinfo). This will write an abbreviated datastream 2261containing only SOI, DQT and/or DHT markers, and EOI. All the quantization 2262and Huffman tables that are currently defined in the compression object will 2263be emitted unless their sent_tables flag is already TRUE, and then all the 2264sent_tables flags will be set TRUE. 2265 2266A sure-fire way to create matching tables-only and abbreviated image files 2267is to proceed as follows: 2268 2269 create JPEG compression object 2270 set JPEG parameters 2271 set destination to tables-only file 2272 jpeg_write_tables(&cinfo); 2273 set destination to image file 2274 jpeg_start_compress(&cinfo, FALSE); 2275 write data... 2276 jpeg_finish_compress(&cinfo); 2277 2278Since the JPEG parameters are not altered between writing the table file and 2279the abbreviated image file, the same tables are sure to be used. Of course, 2280you can repeat the jpeg_start_compress() ... jpeg_finish_compress() sequence 2281many times to produce many abbreviated image files matching the table file. 2282 2283You cannot suppress output of the computed Huffman tables when Huffman 2284optimization is selected. (If you could, there'd be no way to decode the 2285image...) Generally, you don't want to set optimize_coding = TRUE when 2286you are trying to produce abbreviated files. 2287 2288In some cases you might want to compress an image using tables which are 2289not stored in the application, but are defined in an interchange or 2290tables-only file readable by the application. This can be done by setting up 2291a JPEG decompression object to read the specification file, then copying the 2292tables into your compression object. See jpeg_copy_critical_parameters() 2293for an example of copying quantization tables. 2294 2295 2296To read abbreviated image files, you simply need to load the proper tables 2297into the decompression object before trying to read the abbreviated image. 2298If the proper tables are stored in the application program, you can just 2299allocate the table structs and fill in their contents directly. For example, 2300to load a fixed quantization table into table slot "n": 2301 2302 if (cinfo.quant_tbl_ptrs[n] == NULL) 2303 cinfo.quant_tbl_ptrs[n] = jpeg_alloc_quant_table((j_common_ptr) &cinfo); 2304 quant_ptr = cinfo.quant_tbl_ptrs[n]; /* quant_ptr is JQUANT_TBL* */ 2305 for (i = 0; i < 64; i++) { 2306 /* Qtable[] is desired quantization table, in natural array order */ 2307 quant_ptr->quantval[i] = Qtable[i]; 2308 } 2309 2310Code to load a fixed Huffman table is typically (for AC table "n"): 2311 2312 if (cinfo.ac_huff_tbl_ptrs[n] == NULL) 2313 cinfo.ac_huff_tbl_ptrs[n] = jpeg_alloc_huff_table((j_common_ptr) &cinfo); 2314 huff_ptr = cinfo.ac_huff_tbl_ptrs[n]; /* huff_ptr is JHUFF_TBL* */ 2315 for (i = 1; i <= 16; i++) { 2316 /* counts[i] is number of Huffman codes of length i bits, i=1..16 */ 2317 huff_ptr->bits[i] = counts[i]; 2318 } 2319 for (i = 0; i < 256; i++) { 2320 /* symbols[] is the list of Huffman symbols, in code-length order */ 2321 huff_ptr->huffval[i] = symbols[i]; 2322 } 2323 2324(Note that trying to set cinfo.quant_tbl_ptrs[n] to point directly at a 2325constant JQUANT_TBL object is not safe. If the incoming file happened to 2326contain a quantization table definition, your master table would get 2327overwritten! Instead allocate a working table copy and copy the master table 2328into it, as illustrated above. Ditto for Huffman tables, of course.) 2329 2330You might want to read the tables from a tables-only file, rather than 2331hard-wiring them into your application. The jpeg_read_header() call is 2332sufficient to read a tables-only file. You must pass a second parameter of 2333FALSE to indicate that you do not require an image to be present. Thus, the 2334typical scenario is 2335 2336 create JPEG decompression object 2337 set source to tables-only file 2338 jpeg_read_header(&cinfo, FALSE); 2339 set source to abbreviated image file 2340 jpeg_read_header(&cinfo, TRUE); 2341 set decompression parameters 2342 jpeg_start_decompress(&cinfo); 2343 read data... 2344 jpeg_finish_decompress(&cinfo); 2345 2346In some cases, you may want to read a file without knowing whether it contains 2347an image or just tables. In that case, pass FALSE and check the return value 2348from jpeg_read_header(): it will be JPEG_HEADER_OK if an image was found, 2349JPEG_HEADER_TABLES_ONLY if only tables were found. (A third return value, 2350JPEG_SUSPENDED, is possible when using a suspending data source manager.) 2351Note that jpeg_read_header() will not complain if you read an abbreviated 2352image for which you haven't loaded the missing tables; the missing-table check 2353occurs later, in jpeg_start_decompress(). 2354 2355 2356It is possible to read a series of images from a single source file by 2357repeating the jpeg_read_header() ... jpeg_finish_decompress() sequence, 2358without releasing/recreating the JPEG object or the data source module. 2359(If you did reinitialize, any partial bufferload left in the data source 2360buffer at the end of one image would be discarded, causing you to lose the 2361start of the next image.) When you use this method, stored tables are 2362automatically carried forward, so some of the images can be abbreviated images 2363that depend on tables from earlier images. 2364 2365If you intend to write a series of images into a single destination file, 2366you might want to make a specialized data destination module that doesn't 2367flush the output buffer at term_destination() time. This would speed things 2368up by some trifling amount. Of course, you'd need to remember to flush the 2369buffer after the last image. You can make the later images be abbreviated 2370ones by passing FALSE to jpeg_start_compress(). 2371 2372 2373Special markers 2374--------------- 2375 2376Some applications may need to insert or extract special data in the JPEG 2377datastream. The JPEG standard provides marker types "COM" (comment) and 2378"APP0" through "APP15" (application) to hold application-specific data. 2379Unfortunately, the use of these markers is not specified by the standard. 2380COM markers are fairly widely used to hold user-supplied text. The JFIF file 2381format spec uses APP0 markers with specified initial strings to hold certain 2382data. Adobe applications use APP14 markers beginning with the string "Adobe" 2383for miscellaneous data. Other APPn markers are rarely seen, but might 2384contain almost anything. 2385 2386If you wish to store user-supplied text, we recommend you use COM markers 2387and place readable 7-bit ASCII text in them. Newline conventions are not 2388standardized --- expect to find LF (Unix style), CR/LF (DOS style), or CR 2389(Mac style). A robust COM reader should be able to cope with random binary 2390garbage, including nulls, since some applications generate COM markers 2391containing non-ASCII junk. (But yours should not be one of them.) 2392 2393For program-supplied data, use an APPn marker, and be sure to begin it with an 2394identifying string so that you can tell whether the marker is actually yours. 2395It's probably best to avoid using APP0 or APP14 for any private markers. 2396(NOTE: the upcoming SPIFF standard will use APP8 markers; we recommend you 2397not use APP8 markers for any private purposes, either.) 2398 2399Keep in mind that at most 65533 bytes can be put into one marker, but you 2400can have as many markers as you like. 2401 2402By default, the IJG compression library will write a JFIF APP0 marker if the 2403selected JPEG colorspace is grayscale or YCbCr, or an Adobe APP14 marker if 2404the selected colorspace is RGB, CMYK, or YCCK. You can disable this, but 2405we don't recommend it. The decompression library will recognize JFIF and 2406Adobe markers and will set the JPEG colorspace properly when one is found. 2407 2408 2409You can write special markers immediately following the datastream header by 2410calling jpeg_write_marker() after jpeg_start_compress() and before the first 2411call to jpeg_write_scanlines(). When you do this, the markers appear after 2412the SOI and the JFIF APP0 and Adobe APP14 markers (if written), but before 2413all else. Specify the marker type parameter as "JPEG_COM" for COM or 2414"JPEG_APP0 + n" for APPn. (Actually, jpeg_write_marker will let you write 2415any marker type, but we don't recommend writing any other kinds of marker.) 2416For example, to write a user comment string pointed to by comment_text: 2417 jpeg_write_marker(cinfo, JPEG_COM, comment_text, strlen(comment_text)); 2418 2419If it's not convenient to store all the marker data in memory at once, 2420you can instead call jpeg_write_m_header() followed by multiple calls to 2421jpeg_write_m_byte(). If you do it this way, it's your responsibility to 2422call jpeg_write_m_byte() exactly the number of times given in the length 2423parameter to jpeg_write_m_header(). (This method lets you empty the 2424output buffer partway through a marker, which might be important when 2425using a suspending data destination module. In any case, if you are using 2426a suspending destination, you should flush its buffer after inserting 2427any special markers. See "I/O suspension".) 2428 2429Or, if you prefer to synthesize the marker byte sequence yourself, 2430you can just cram it straight into the data destination module. 2431 2432If you are writing JFIF 1.02 extension markers (thumbnail images), don't 2433forget to set cinfo.JFIF_minor_version = 2 so that the encoder will write the 2434correct JFIF version number in the JFIF header marker. The library's default 2435is to write version 1.01, but that's wrong if you insert any 1.02 extension 2436markers. (We could probably get away with just defaulting to 1.02, but there 2437used to be broken decoders that would complain about unknown minor version 2438numbers. To reduce compatibility risks it's safest not to write 1.02 unless 2439you are actually using 1.02 extensions.) 2440 2441 2442When reading, two methods of handling special markers are available: 24431. You can ask the library to save the contents of COM and/or APPn markers 2444into memory, and then examine them at your leisure afterwards. 24452. You can supply your own routine to process COM and/or APPn markers 2446on-the-fly as they are read. 2447The first method is simpler to use, especially if you are using a suspending 2448data source; writing a marker processor that copes with input suspension is 2449not easy (consider what happens if the marker is longer than your available 2450input buffer). However, the second method conserves memory since the marker 2451data need not be kept around after it's been processed. 2452 2453For either method, you'd normally set up marker handling after creating a 2454decompression object and before calling jpeg_read_header(), because the 2455markers of interest will typically be near the head of the file and so will 2456be scanned by jpeg_read_header. Once you've established a marker handling 2457method, it will be used for the life of that decompression object 2458(potentially many datastreams), unless you change it. Marker handling is 2459determined separately for COM markers and for each APPn marker code. 2460 2461 2462To save the contents of special markers in memory, call 2463 jpeg_save_markers(cinfo, marker_code, length_limit) 2464where marker_code is the marker type to save, JPEG_COM or JPEG_APP0+n. 2465(To arrange to save all the special marker types, you need to call this 2466routine 17 times, for COM and APP0-APP15.) If the incoming marker is longer 2467than length_limit data bytes, only length_limit bytes will be saved; this 2468parameter allows you to avoid chewing up memory when you only need to see the 2469first few bytes of a potentially large marker. If you want to save all the 2470data, set length_limit to 0xFFFF; that is enough since marker lengths are only 247116 bits. As a special case, setting length_limit to 0 prevents that marker 2472type from being saved at all. (That is the default behavior, in fact.) 2473 2474After jpeg_read_header() completes, you can examine the special markers by 2475following the cinfo->marker_list pointer chain. All the special markers in 2476the file appear in this list, in order of their occurrence in the file (but 2477omitting any markers of types you didn't ask for). Both the original data 2478length and the saved data length are recorded for each list entry; the latter 2479will not exceed length_limit for the particular marker type. Note that these 2480lengths exclude the marker length word, whereas the stored representation 2481within the JPEG file includes it. (Hence the maximum data length is really 2482only 65533.) 2483 2484It is possible that additional special markers appear in the file beyond the 2485SOS marker at which jpeg_read_header stops; if so, the marker list will be 2486extended during reading of the rest of the file. This is not expected to be 2487common, however. If you are short on memory you may want to reset the length 2488limit to zero for all marker types after finishing jpeg_read_header, to 2489ensure that the max_memory_to_use setting cannot be exceeded due to addition 2490of later markers. 2491 2492The marker list remains stored until you call jpeg_finish_decompress or 2493jpeg_abort, at which point the memory is freed and the list is set to empty. 2494(jpeg_destroy also releases the storage, of course.) 2495 2496Note that the library is internally interested in APP0 and APP14 markers; 2497if you try to set a small nonzero length limit on these types, the library 2498will silently force the length up to the minimum it wants. (But you can set 2499a zero length limit to prevent them from being saved at all.) Also, in a 250016-bit environment, the maximum length limit may be constrained to less than 250165533 by malloc() limitations. It is therefore best not to assume that the 2502effective length limit is exactly what you set it to be. 2503 2504 2505If you want to supply your own marker-reading routine, you do it by calling 2506jpeg_set_marker_processor(). A marker processor routine must have the 2507signature 2508 boolean jpeg_marker_parser_method (j_decompress_ptr cinfo) 2509Although the marker code is not explicitly passed, the routine can find it 2510in cinfo->unread_marker. At the time of call, the marker proper has been 2511read from the data source module. The processor routine is responsible for 2512reading the marker length word and the remaining parameter bytes, if any. 2513Return TRUE to indicate success. (FALSE should be returned only if you are 2514using a suspending data source and it tells you to suspend. See the standard 2515marker processors in jdmarker.c for appropriate coding methods if you need to 2516use a suspending data source.) 2517 2518If you override the default APP0 or APP14 processors, it is up to you to 2519recognize JFIF and Adobe markers if you want colorspace recognition to occur 2520properly. We recommend copying and extending the default processors if you 2521want to do that. (A better idea is to save these marker types for later 2522examination by calling jpeg_save_markers(); that method doesn't interfere 2523with the library's own processing of these markers.) 2524 2525jpeg_set_marker_processor() and jpeg_save_markers() are mutually exclusive 2526--- if you call one it overrides any previous call to the other, for the 2527particular marker type specified. 2528 2529A simple example of an external COM processor can be found in djpeg.c. 2530Also, see jpegtran.c for an example of using jpeg_save_markers. 2531 2532 2533Raw (downsampled) image data 2534---------------------------- 2535 2536Some applications need to supply already-downsampled image data to the JPEG 2537compressor, or to receive raw downsampled data from the decompressor. The 2538library supports this requirement by allowing the application to write or 2539read raw data, bypassing the normal preprocessing or postprocessing steps. 2540The interface is different from the standard one and is somewhat harder to 2541use. If your interest is merely in bypassing color conversion, we recommend 2542that you use the standard interface and simply set jpeg_color_space = 2543in_color_space (or jpeg_color_space = out_color_space for decompression). 2544The mechanism described in this section is necessary only to supply or 2545receive downsampled image data, in which not all components have the same 2546dimensions. 2547 2548 2549To compress raw data, you must supply the data in the colorspace to be used 2550in the JPEG file (please read the earlier section on Special color spaces) 2551and downsampled to the sampling factors specified in the JPEG parameters. 2552You must supply the data in the format used internally by the JPEG library, 2553namely a JSAMPIMAGE array. This is an array of pointers to two-dimensional 2554arrays, each of type JSAMPARRAY. Each 2-D array holds the values for one 2555color component. This structure is necessary since the components are of 2556different sizes. If the image dimensions are not a multiple of the MCU size, 2557you must also pad the data correctly (usually, this is done by replicating 2558the last column and/or row). The data must be padded to a multiple of a DCT 2559block in each component: that is, each downsampled row must contain a 2560multiple of 8 valid samples, and there must be a multiple of 8 sample rows 2561for each component. (For applications such as conversion of digital TV 2562images, the standard image size is usually a multiple of the DCT block size, 2563so that no padding need actually be done.) 2564 2565The procedure for compression of raw data is basically the same as normal 2566compression, except that you call jpeg_write_raw_data() in place of 2567jpeg_write_scanlines(). Before calling jpeg_start_compress(), you must do 2568the following: 2569 * Set cinfo->raw_data_in to TRUE. (It is set FALSE by jpeg_set_defaults().) 2570 This notifies the library that you will be supplying raw data. 2571 Furthermore, set cinfo->do_fancy_downsampling to FALSE if you want to use 2572 real downsampled data. (It is set TRUE by jpeg_set_defaults().) 2573 * Ensure jpeg_color_space is correct --- an explicit jpeg_set_colorspace() 2574 call is a good idea. Note that since color conversion is bypassed, 2575 in_color_space is ignored, except that jpeg_set_defaults() uses it to 2576 choose the default jpeg_color_space setting. 2577 * Ensure the sampling factors, cinfo->comp_info[i].h_samp_factor and 2578 cinfo->comp_info[i].v_samp_factor, are correct. Since these indicate the 2579 dimensions of the data you are supplying, it's wise to set them 2580 explicitly, rather than assuming the library's defaults are what you want. 2581 2582To pass raw data to the library, call jpeg_write_raw_data() in place of 2583jpeg_write_scanlines(). The two routines work similarly except that 2584jpeg_write_raw_data takes a JSAMPIMAGE data array rather than JSAMPARRAY. 2585The scanlines count passed to and returned from jpeg_write_raw_data is 2586measured in terms of the component with the largest v_samp_factor. 2587 2588jpeg_write_raw_data() processes one MCU row per call, which is to say 2589v_samp_factor*DCTSIZE sample rows of each component. The passed num_lines 2590value must be at least max_v_samp_factor*DCTSIZE, and the return value will 2591be exactly that amount (or possibly some multiple of that amount, in future 2592library versions). This is true even on the last call at the bottom of the 2593image; don't forget to pad your data as necessary. 2594 2595The required dimensions of the supplied data can be computed for each 2596component as 2597 cinfo->comp_info[i].width_in_blocks*DCTSIZE samples per row 2598 cinfo->comp_info[i].height_in_blocks*DCTSIZE rows in image 2599after jpeg_start_compress() has initialized those fields. If the valid data 2600is smaller than this, it must be padded appropriately. For some sampling 2601factors and image sizes, additional dummy DCT blocks are inserted to make 2602the image a multiple of the MCU dimensions. The library creates such dummy 2603blocks itself; it does not read them from your supplied data. Therefore you 2604need never pad by more than DCTSIZE samples. An example may help here. 2605Assume 2h2v downsampling of YCbCr data, that is 2606 cinfo->comp_info[0].h_samp_factor = 2 for Y 2607 cinfo->comp_info[0].v_samp_factor = 2 2608 cinfo->comp_info[1].h_samp_factor = 1 for Cb 2609 cinfo->comp_info[1].v_samp_factor = 1 2610 cinfo->comp_info[2].h_samp_factor = 1 for Cr 2611 cinfo->comp_info[2].v_samp_factor = 1 2612and suppose that the nominal image dimensions (cinfo->image_width and 2613cinfo->image_height) are 101x101 pixels. Then jpeg_start_compress() will 2614compute downsampled_width = 101 and width_in_blocks = 13 for Y, 2615downsampled_width = 51 and width_in_blocks = 7 for Cb and Cr (and the same 2616for the height fields). You must pad the Y data to at least 13*8 = 104 2617columns and rows, the Cb/Cr data to at least 7*8 = 56 columns and rows. The 2618MCU height is max_v_samp_factor = 2 DCT rows so you must pass at least 16 2619scanlines on each call to jpeg_write_raw_data(), which is to say 16 actual 2620sample rows of Y and 8 each of Cb and Cr. A total of 7 MCU rows are needed, 2621so you must pass a total of 7*16 = 112 "scanlines". The last DCT block row 2622of Y data is dummy, so it doesn't matter what you pass for it in the data 2623arrays, but the scanlines count must total up to 112 so that all of the Cb 2624and Cr data gets passed. 2625 2626Output suspension is supported with raw-data compression: if the data 2627destination module suspends, jpeg_write_raw_data() will return 0. 2628In this case the same data rows must be passed again on the next call. 2629 2630 2631Decompression with raw data output implies bypassing all postprocessing. 2632You must deal with the color space and sampling factors present in the 2633incoming file. If your application only handles, say, 2h1v YCbCr data, 2634you must check for and fail on other color spaces or other sampling factors. 2635The library will not convert to a different color space for you. 2636 2637To obtain raw data output, set cinfo->raw_data_out = TRUE before 2638jpeg_start_decompress() (it is set FALSE by jpeg_read_header()). Be sure to 2639verify that the color space and sampling factors are ones you can handle. 2640Furthermore, set cinfo->do_fancy_upsampling = FALSE if you want to get real 2641downsampled data (it is set TRUE by jpeg_read_header()). 2642Then call jpeg_read_raw_data() in place of jpeg_read_scanlines(). The 2643decompression process is otherwise the same as usual. 2644 2645jpeg_read_raw_data() returns one MCU row per call, and thus you must pass a 2646buffer of at least max_v_samp_factor*DCTSIZE scanlines (scanline counting is 2647the same as for raw-data compression). The buffer you pass must be large 2648enough to hold the actual data plus padding to DCT-block boundaries. As with 2649compression, any entirely dummy DCT blocks are not processed so you need not 2650allocate space for them, but the total scanline count includes them. The 2651above example of computing buffer dimensions for raw-data compression is 2652equally valid for decompression. 2653 2654Input suspension is supported with raw-data decompression: if the data source 2655module suspends, jpeg_read_raw_data() will return 0. You can also use 2656buffered-image mode to read raw data in multiple passes. 2657 2658 2659Really raw data: DCT coefficients 2660--------------------------------- 2661 2662It is possible to read or write the contents of a JPEG file as raw DCT 2663coefficients. This facility is mainly intended for use in lossless 2664transcoding between different JPEG file formats. Other possible applications 2665include lossless cropping of a JPEG image, lossless reassembly of a 2666multi-strip or multi-tile TIFF/JPEG file into a single JPEG datastream, etc. 2667 2668To read the contents of a JPEG file as DCT coefficients, open the file and do 2669jpeg_read_header() as usual. But instead of calling jpeg_start_decompress() 2670and jpeg_read_scanlines(), call jpeg_read_coefficients(). This will read the 2671entire image into a set of virtual coefficient-block arrays, one array per 2672component. The return value is a pointer to an array of virtual-array 2673descriptors. Each virtual array can be accessed directly using the JPEG 2674memory manager's access_virt_barray method (see Memory management, below, 2675and also read structure.txt's discussion of virtual array handling). Or, 2676for simple transcoding to a different JPEG file format, the array list can 2677just be handed directly to jpeg_write_coefficients(). 2678 2679Each block in the block arrays contains quantized coefficient values in 2680normal array order (not JPEG zigzag order). The block arrays contain only 2681DCT blocks containing real data; any entirely-dummy blocks added to fill out 2682interleaved MCUs at the right or bottom edges of the image are discarded 2683during reading and are not stored in the block arrays. (The size of each 2684block array can be determined from the width_in_blocks and height_in_blocks 2685fields of the component's comp_info entry.) This is also the data format 2686expected by jpeg_write_coefficients(). 2687 2688When you are done using the virtual arrays, call jpeg_finish_decompress() 2689to release the array storage and return the decompression object to an idle 2690state; or just call jpeg_destroy() if you don't need to reuse the object. 2691 2692If you use a suspending data source, jpeg_read_coefficients() will return 2693NULL if it is forced to suspend; a non-NULL return value indicates successful 2694completion. You need not test for a NULL return value when using a 2695non-suspending data source. 2696 2697It is also possible to call jpeg_read_coefficients() to obtain access to the 2698decoder's coefficient arrays during a normal decode cycle in buffered-image 2699mode. This frammish might be useful for progressively displaying an incoming 2700image and then re-encoding it without loss. To do this, decode in buffered- 2701image mode as discussed previously, then call jpeg_read_coefficients() after 2702the last jpeg_finish_output() call. The arrays will be available for your use 2703until you call jpeg_finish_decompress(). 2704 2705 2706To write the contents of a JPEG file as DCT coefficients, you must provide 2707the DCT coefficients stored in virtual block arrays. You can either pass 2708block arrays read from an input JPEG file by jpeg_read_coefficients(), or 2709allocate virtual arrays from the JPEG compression object and fill them 2710yourself. In either case, jpeg_write_coefficients() is substituted for 2711jpeg_start_compress() and jpeg_write_scanlines(). Thus the sequence is 2712 * Create compression object 2713 * Set all compression parameters as necessary 2714 * Request virtual arrays if needed 2715 * jpeg_write_coefficients() 2716 * jpeg_finish_compress() 2717 * Destroy or re-use compression object 2718jpeg_write_coefficients() is passed a pointer to an array of virtual block 2719array descriptors; the number of arrays is equal to cinfo.num_components. 2720 2721The virtual arrays need only have been requested, not realized, before 2722jpeg_write_coefficients() is called. A side-effect of 2723jpeg_write_coefficients() is to realize any virtual arrays that have been 2724requested from the compression object's memory manager. Thus, when obtaining 2725the virtual arrays from the compression object, you should fill the arrays 2726after calling jpeg_write_coefficients(). The data is actually written out 2727when you call jpeg_finish_compress(); jpeg_write_coefficients() only writes 2728the file header. 2729 2730When writing raw DCT coefficients, it is crucial that the JPEG quantization 2731tables and sampling factors match the way the data was encoded, or the 2732resulting file will be invalid. For transcoding from an existing JPEG file, 2733we recommend using jpeg_copy_critical_parameters(). This routine initializes 2734all the compression parameters to default values (like jpeg_set_defaults()), 2735then copies the critical information from a source decompression object. 2736The decompression object should have just been used to read the entire 2737JPEG input file --- that is, it should be awaiting jpeg_finish_decompress(). 2738 2739jpeg_write_coefficients() marks all tables stored in the compression object 2740as needing to be written to the output file (thus, it acts like 2741jpeg_start_compress(cinfo, TRUE)). This is for safety's sake, to avoid 2742emitting abbreviated JPEG files by accident. If you really want to emit an 2743abbreviated JPEG file, call jpeg_suppress_tables(), or set the tables' 2744individual sent_table flags, between calling jpeg_write_coefficients() and 2745jpeg_finish_compress(). 2746 2747 2748Progress monitoring 2749------------------- 2750 2751Some applications may need to regain control from the JPEG library every so 2752often. The typical use of this feature is to produce a percent-done bar or 2753other progress display. (For a simple example, see cjpeg.c or djpeg.c.) 2754Although you do get control back frequently during the data-transferring pass 2755(the jpeg_read_scanlines or jpeg_write_scanlines loop), any additional passes 2756will occur inside jpeg_finish_compress or jpeg_start_decompress; those 2757routines may take a long time to execute, and you don't get control back 2758until they are done. 2759 2760You can define a progress-monitor routine which will be called periodically 2761by the library. No guarantees are made about how often this call will occur, 2762so we don't recommend you use it for mouse tracking or anything like that. 2763At present, a call will occur once per MCU row, scanline, or sample row 2764group, whichever unit is convenient for the current processing mode; so the 2765wider the image, the longer the time between calls. During the data 2766transferring pass, only one call occurs per call of jpeg_read_scanlines or 2767jpeg_write_scanlines, so don't pass a large number of scanlines at once if 2768you want fine resolution in the progress count. (If you really need to use 2769the callback mechanism for time-critical tasks like mouse tracking, you could 2770insert additional calls inside some of the library's inner loops.) 2771 2772To establish a progress-monitor callback, create a struct jpeg_progress_mgr, 2773fill in its progress_monitor field with a pointer to your callback routine, 2774and set cinfo->progress to point to the struct. The callback will be called 2775whenever cinfo->progress is non-NULL. (This pointer is set to NULL by 2776jpeg_create_compress or jpeg_create_decompress; the library will not change 2777it thereafter. So if you allocate dynamic storage for the progress struct, 2778make sure it will live as long as the JPEG object does. Allocating from the 2779JPEG memory manager with lifetime JPOOL_PERMANENT will work nicely.) You 2780can use the same callback routine for both compression and decompression. 2781 2782The jpeg_progress_mgr struct contains four fields which are set by the library: 2783 long pass_counter; /* work units completed in this pass */ 2784 long pass_limit; /* total number of work units in this pass */ 2785 int completed_passes; /* passes completed so far */ 2786 int total_passes; /* total number of passes expected */ 2787During any one pass, pass_counter increases from 0 up to (not including) 2788pass_limit; the step size is usually but not necessarily 1. The pass_limit 2789value may change from one pass to another. The expected total number of 2790passes is in total_passes, and the number of passes already completed is in 2791completed_passes. Thus the fraction of work completed may be estimated as 2792 completed_passes + (pass_counter/pass_limit) 2793 -------------------------------------------- 2794 total_passes 2795ignoring the fact that the passes may not be equal amounts of work. 2796 2797When decompressing, pass_limit can even change within a pass, because it 2798depends on the number of scans in the JPEG file, which isn't always known in 2799advance. The computed fraction-of-work-done may jump suddenly (if the library 2800discovers it has overestimated the number of scans) or even decrease (in the 2801opposite case). It is not wise to put great faith in the work estimate. 2802 2803When using the decompressor's buffered-image mode, the progress monitor work 2804estimate is likely to be completely unhelpful, because the library has no way 2805to know how many output passes will be demanded of it. Currently, the library 2806sets total_passes based on the assumption that there will be one more output 2807pass if the input file end hasn't yet been read (jpeg_input_complete() isn't 2808TRUE), but no more output passes if the file end has been reached when the 2809output pass is started. This means that total_passes will rise as additional 2810output passes are requested. If you have a way of determining the input file 2811size, estimating progress based on the fraction of the file that's been read 2812will probably be more useful than using the library's value. 2813 2814 2815Memory management 2816----------------- 2817 2818This section covers some key facts about the JPEG library's built-in memory 2819manager. For more info, please read structure.txt's section about the memory 2820manager, and consult the source code if necessary. 2821 2822All memory and temporary file allocation within the library is done via the 2823memory manager. If necessary, you can replace the "back end" of the memory 2824manager to control allocation yourself (for example, if you don't want the 2825library to use malloc() and free() for some reason). 2826 2827Some data is allocated "permanently" and will not be freed until the JPEG 2828object is destroyed. Most data is allocated "per image" and is freed by 2829jpeg_finish_compress, jpeg_finish_decompress, or jpeg_abort. You can call the 2830memory manager yourself to allocate structures that will automatically be 2831freed at these times. Typical code for this is 2832 ptr = (*cinfo->mem->alloc_small) ((j_common_ptr) cinfo, JPOOL_IMAGE, size); 2833Use JPOOL_PERMANENT to get storage that lasts as long as the JPEG object. 2834Use alloc_large instead of alloc_small for anything bigger than a few Kbytes. 2835There are also alloc_sarray and alloc_barray routines that automatically 2836build 2-D sample or block arrays. 2837 2838The library's minimum space requirements to process an image depend on the 2839image's width, but not on its height, because the library ordinarily works 2840with "strip" buffers that are as wide as the image but just a few rows high. 2841Some operating modes (eg, two-pass color quantization) require full-image 2842buffers. Such buffers are treated as "virtual arrays": only the current strip 2843need be in memory, and the rest can be swapped out to a temporary file. 2844 2845If you use the simplest memory manager back end (jmemnobs.c), then no 2846temporary files are used; virtual arrays are simply malloc()'d. Images bigger 2847than memory can be processed only if your system supports virtual memory. 2848The other memory manager back ends support temporary files of various flavors 2849and thus work in machines without virtual memory. They may also be useful on 2850Unix machines if you need to process images that exceed available swap space. 2851 2852When using temporary files, the library will make the in-memory buffers for 2853its virtual arrays just big enough to stay within a "maximum memory" setting. 2854Your application can set this limit by setting cinfo->mem->max_memory_to_use 2855after creating the JPEG object. (Of course, there is still a minimum size for 2856the buffers, so the max-memory setting is effective only if it is bigger than 2857the minimum space needed.) If you allocate any large structures yourself, you 2858must allocate them before jpeg_start_compress() or jpeg_start_decompress() in 2859order to have them counted against the max memory limit. Also keep in mind 2860that space allocated with alloc_small() is ignored, on the assumption that 2861it's too small to be worth worrying about; so a reasonable safety margin 2862should be left when setting max_memory_to_use. 2863 2864If you use the jmemname.c or jmemdos.c memory manager back end, it is 2865important to clean up the JPEG object properly to ensure that the temporary 2866files get deleted. (This is especially crucial with jmemdos.c, where the 2867"temporary files" may be extended-memory segments; if they are not freed, 2868DOS will require a reboot to recover the memory.) Thus, with these memory 2869managers, it's a good idea to provide a signal handler that will trap any 2870early exit from your program. The handler should call either jpeg_abort() 2871or jpeg_destroy() for any active JPEG objects. A handler is not needed with 2872jmemnobs.c, and shouldn't be necessary with jmemansi.c or jmemmac.c either, 2873since the C library is supposed to take care of deleting files made with 2874tmpfile(). 2875 2876 2877Memory usage 2878------------ 2879 2880Working memory requirements while performing compression or decompression 2881depend on image dimensions, image characteristics (such as colorspace and 2882JPEG process), and operating mode (application-selected options). 2883 2884As of v6b, the decompressor requires: 2885 1. About 24K in more-or-less-fixed-size data. This varies a bit depending 2886 on operating mode and image characteristics (particularly color vs. 2887 grayscale), but it doesn't depend on image dimensions. 2888 2. Strip buffers (of size proportional to the image width) for IDCT and 2889 upsampling results. The worst case for commonly used sampling factors 2890 is about 34 bytes * width in pixels for a color image. A grayscale image 2891 only needs about 8 bytes per pixel column. 2892 3. A full-image DCT coefficient buffer is needed to decode a multi-scan JPEG 2893 file (including progressive JPEGs), or whenever you select buffered-image 2894 mode. This takes 2 bytes/coefficient. At typical 2x2 sampling, that's 2895 3 bytes per pixel for a color image. Worst case (1x1 sampling) requires 2896 6 bytes/pixel. For grayscale, figure 2 bytes/pixel. 2897 4. To perform 2-pass color quantization, the decompressor also needs a 2898 128K color lookup table and a full-image pixel buffer (3 bytes/pixel). 2899This does not count any memory allocated by the application, such as a 2900buffer to hold the final output image. 2901 2902The above figures are valid for 8-bit JPEG data precision and a machine with 290332-bit ints. For 12-bit JPEG data, double the size of the strip buffers and 2904quantization pixel buffer. The "fixed-size" data will be somewhat smaller 2905with 16-bit ints, larger with 64-bit ints. Also, CMYK or other unusual 2906color spaces will require different amounts of space. 2907 2908The full-image coefficient and pixel buffers, if needed at all, do not 2909have to be fully RAM resident; you can have the library use temporary 2910files instead when the total memory usage would exceed a limit you set. 2911(But if your OS supports virtual memory, it's probably better to just use 2912jmemnobs and let the OS do the swapping.) 2913 2914The compressor's memory requirements are similar, except that it has no need 2915for color quantization. Also, it needs a full-image DCT coefficient buffer 2916if Huffman-table optimization is asked for, even if progressive mode is not 2917requested. 2918 2919If you need more detailed information about memory usage in a particular 2920situation, you can enable the MEM_STATS code in jmemmgr.c. 2921 2922 2923Library compile-time options 2924---------------------------- 2925 2926A number of compile-time options are available by modifying jmorecfg.h. 2927 2928The JPEG standard provides for both the baseline 8-bit DCT process and 2929a 12-bit DCT process. The IJG code supports 12-bit lossy JPEG if you define 2930BITS_IN_JSAMPLE as 12 rather than 8. Note that this causes JSAMPLE to be 2931larger than a char, so it affects the surrounding application's image data. 2932The sample applications cjpeg and djpeg can support 12-bit mode only for PPM 2933and GIF file formats; you must disable the other file formats to compile a 293412-bit cjpeg or djpeg. (install.txt has more information about that.) 2935At present, a 12-bit library can handle *only* 12-bit images, not both 2936precisions. (If you need to include both 8- and 12-bit libraries in a single 2937application, you could probably do it by defining NEED_SHORT_EXTERNAL_NAMES 2938for just one of the copies. You'd have to access the 8-bit and 12-bit copies 2939from separate application source files. This is untested ... if you try it, 2940we'd like to hear whether it works!) 2941 2942Note that a 12-bit library always compresses in Huffman optimization mode, 2943in order to generate valid Huffman tables. This is necessary because our 2944default Huffman tables only cover 8-bit data. If you need to output 12-bit 2945files in one pass, you'll have to supply suitable default Huffman tables. 2946You may also want to supply your own DCT quantization tables; the existing 2947quality-scaling code has been developed for 8-bit use, and probably doesn't 2948generate especially good tables for 12-bit. 2949 2950The maximum number of components (color channels) in the image is determined 2951by MAX_COMPONENTS. The JPEG standard allows up to 255 components, but we 2952expect that few applications will need more than four or so. 2953 2954On machines with unusual data type sizes, you may be able to improve 2955performance or reduce memory space by tweaking the various typedefs in 2956jmorecfg.h. In particular, on some RISC CPUs, access to arrays of "short"s 2957is quite slow; consider trading memory for speed by making JCOEF, INT16, and 2958UINT16 be "int" or "unsigned int". UINT8 is also a candidate to become int. 2959You probably don't want to make JSAMPLE be int unless you have lots of memory 2960to burn. 2961 2962You can reduce the size of the library by compiling out various optional 2963functions. To do this, undefine xxx_SUPPORTED symbols as necessary. 2964 2965You can also save a few K by not having text error messages in the library; 2966the standard error message table occupies about 5Kb. This is particularly 2967reasonable for embedded applications where there's no good way to display 2968a message anyway. To do this, remove the creation of the message table 2969(jpeg_std_message_table[]) from jerror.c, and alter format_message to do 2970something reasonable without it. You could output the numeric value of the 2971message code number, for example. If you do this, you can also save a couple 2972more K by modifying the TRACEMSn() macros in jerror.h to expand to nothing; 2973you don't need trace capability anyway, right? 2974 2975 2976Portability considerations 2977-------------------------- 2978 2979The JPEG library has been written to be extremely portable; the sample 2980applications cjpeg and djpeg are slightly less so. This section summarizes 2981the design goals in this area. (If you encounter any bugs that cause the 2982library to be less portable than is claimed here, we'd appreciate hearing 2983about them.) 2984 2985The code works fine on ANSI C, C++, and pre-ANSI C compilers, using any of 2986the popular system include file setups, and some not-so-popular ones too. 2987See install.txt for configuration procedures. 2988 2989The code is not dependent on the exact sizes of the C data types. As 2990distributed, we make the assumptions that 2991 char is at least 8 bits wide 2992 short is at least 16 bits wide 2993 int is at least 16 bits wide 2994 long is at least 32 bits wide 2995(These are the minimum requirements of the ANSI C standard.) Wider types will 2996work fine, although memory may be used inefficiently if char is much larger 2997than 8 bits or short is much bigger than 16 bits. The code should work 2998equally well with 16- or 32-bit ints. 2999 3000In a system where these assumptions are not met, you may be able to make the 3001code work by modifying the typedefs in jmorecfg.h. However, you will probably 3002have difficulty if int is less than 16 bits wide, since references to plain 3003int abound in the code. 3004 3005char can be either signed or unsigned, although the code runs faster if an 3006unsigned char type is available. If char is wider than 8 bits, you will need 3007to redefine JOCTET and/or provide custom data source/destination managers so 3008that JOCTET represents exactly 8 bits of data on external storage. 3009 3010The JPEG library proper does not assume ASCII representation of characters. 3011But some of the image file I/O modules in cjpeg/djpeg do have ASCII 3012dependencies in file-header manipulation; so does cjpeg's select_file_type() 3013routine. 3014 3015The JPEG library does not rely heavily on the C library. In particular, C 3016stdio is used only by the data source/destination modules and the error 3017handler, all of which are application-replaceable. (cjpeg/djpeg are more 3018heavily dependent on stdio.) malloc and free are called only from the memory 3019manager "back end" module, so you can use a different memory allocator by 3020replacing that one file. 3021 3022The code generally assumes that C names must be unique in the first 15 3023characters. However, global function names can be made unique in the 3024first 6 characters by defining NEED_SHORT_EXTERNAL_NAMES. 3025 3026More info about porting the code may be gleaned by reading jconfig.txt, 3027jmorecfg.h, and jinclude.h. 3028 3029 3030Notes for MS-DOS implementors 3031----------------------------- 3032 3033The IJG code is designed to work efficiently in 80x86 "small" or "medium" 3034memory models (i.e., data pointers are 16 bits unless explicitly declared 3035"far"; code pointers can be either size). You may be able to use small 3036model to compile cjpeg or djpeg by itself, but you will probably have to use 3037medium model for any larger application. This won't make much difference in 3038performance. You *will* take a noticeable performance hit if you use a 3039large-data memory model (perhaps 10%-25%), and you should avoid "huge" model 3040if at all possible. 3041 3042The JPEG library typically needs 2Kb-3Kb of stack space. It will also 3043malloc about 20K-30K of near heap space while executing (and lots of far 3044heap, but that doesn't count in this calculation). This figure will vary 3045depending on selected operating mode, and to a lesser extent on image size. 3046There is also about 5Kb-6Kb of constant data which will be allocated in the 3047near data segment (about 4Kb of this is the error message table). 3048Thus you have perhaps 20K available for other modules' static data and near 3049heap space before you need to go to a larger memory model. The C library's 3050static data will account for several K of this, but that still leaves a good 3051deal for your needs. (If you are tight on space, you could reduce the sizes 3052of the I/O buffers allocated by jdatasrc.c and jdatadst.c, say from 4K to 30531K. Another possibility is to move the error message table to far memory; 3054this should be doable with only localized hacking on jerror.c.) 3055 3056About 2K of the near heap space is "permanent" memory that will not be 3057released until you destroy the JPEG object. This is only an issue if you 3058save a JPEG object between compression or decompression operations. 3059 3060Far data space may also be a tight resource when you are dealing with large 3061images. The most memory-intensive case is decompression with two-pass color 3062quantization, or single-pass quantization to an externally supplied color 3063map. This requires a 128Kb color lookup table plus strip buffers amounting 3064to about 40 bytes per column for typical sampling ratios (eg, about 25600 3065bytes for a 640-pixel-wide image). You may not be able to process wide 3066images if you have large data structures of your own. 3067 3068Of course, all of these concerns vanish if you use a 32-bit flat-memory-model 3069compiler, such as DJGPP or Watcom C. We highly recommend flat model if you 3070can use it; the JPEG library is significantly faster in flat model. 3071