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