1USING THE IJG JPEG LIBRARY 2 3Copyright (C) 1994, Thomas G. Lane. 4This file is part of the Independent JPEG Group's software. 5For conditions of distribution and use, see the accompanying README file. 6 7 8This file describes how to use the IJG JPEG library within an application 9program. Read it if you want to write a program that uses the library. 10 11The file example.c provides heavily commented skeleton code for calling the 12JPEG library. Also see jpeglib.h (the include file to be used by application 13programs) for full details about data structures and function parameter lists. 14The library source code, of course, is the ultimate reference. 15 16Note that there have been *major* changes from the application interface 17presented by IJG version 4 and earlier versions. The old design had several 18inherent limitations, and it had accumulated a lot of cruft as we added 19features while trying to minimize application-interface changes. We have 20sacrificed backward compatibility in the version 5 rewrite, but we think the 21improvements justify this. 22 23 24TABLE OF CONTENTS 25----------------- 26 27Overview: 28 Functions provided by the library 29 Outline of typical usage 30Basic library usage: 31 Data formats 32 Compression details 33 Decompression details 34 Mechanics of usage: include files, linking, etc 35Advanced features: 36 Compression parameter selection 37 Decompression parameter selection 38 Special color spaces 39 Error handling 40 Compressed data handling (source and destination managers) 41 I/O suspension 42 Abbreviated datastreams and multiple images 43 Special markers 44 Raw (downsampled) image data 45 Progress monitoring 46 Memory management 47 Library compile-time options 48 Portability considerations 49 Notes for MS-DOS implementors 50 51You should read at least the overview and basic usage sections before trying 52to program with the library. The sections on advanced features can be read 53if and when you need them. 54 55 56OVERVIEW 57======== 58 59Functions provided by the library 60--------------------------------- 61 62The IJG JPEG library provides C code to read and write JPEG-compressed image 63files. The surrounding application program receives or supplies image data a 64scanline at a time, using a straightforward uncompressed image format. All 65details of color conversion and other preprocessing/postprocessing can be 66handled by the library. 67 68The library includes a substantial amount of code that is not covered by the 69JPEG standard but is necessary for typical applications of JPEG. These 70functions preprocess the image before JPEG compression or postprocess it after 71decompression. They include colorspace conversion, downsampling/upsampling, 72and color quantization. The application indirectly selects use of this code 73by specifying the format in which it wishes to supply or receive image data. 74For example, if colormapped output is requested, then the decompression 75library automatically invokes color quantization. 76 77A wide range of quality vs. speed tradeoffs are possible in JPEG processing, 78and even more so in decompression postprocessing. The decompression library 79provides multiple implementations that cover most of the useful tradeoffs, 80ranging from very-high-quality down to fast-preview operation. On the 81compression side we have generally not provided low-quality choices, since 82compression is normally less time-critical. It should be understood that the 83low-quality modes may not meet the JPEG standard's accuracy requirements; 84nonetheless, they are useful for viewers. 85 86A word about functions *not* provided by the library. We handle a subset of 87the ISO JPEG standard; most baseline and extended-sequential JPEG processes 88are supported. (Our subset includes all features now in common use.) 89Unsupported ISO options include: 90 * Progressive storage (may be supported in future versions) 91 * Hierarchical storage 92 * Lossless JPEG 93 * Arithmetic entropy coding (unsupported for legal reasons) 94 * DNL marker 95 * Nonintegral subsampling ratios 96We support both 8- and 12-bit data precision, but this is a compile-time 97choice rather than a run-time choice; hence it is difficult to use both 98precisions in a single application. 99 100By itself, the library handles only interchange JPEG datastreams --- in 101particular the widely used JFIF file format. The library can be used by 102surrounding code to process interchange or abbreviated JPEG datastreams that 103are embedded in more complex file formats. (For example, we anticipate that 104Sam Leffler's LIBTIFF library will use this code to support the revised TIFF 105JPEG format.) 106 107 108Outline of typical usage 109------------------------ 110 111The rough outline of a JPEG compression operation is: 112 113 Allocate and initialize a JPEG compression object 114 Specify the destination for the compressed data (eg, a file) 115 Set parameters for compression, including image size & colorspace 116 jpeg_start_compress(...); 117 while (scan lines remain to be written) 118 jpeg_write_scanlines(...); 119 jpeg_finish_compress(...); 120 Release the JPEG compression object 121 122A JPEG compression object holds parameters and working state for the JPEG 123library. We make creation/destruction of the object separate from starting 124or finishing compression of an image; the same object can be re-used for a 125series of image compression operations. This makes it easy to re-use the 126same parameter settings for a sequence of images. Re-use of a JPEG object 127also has important implications for processing abbreviated JPEG datastreams, 128as discussed later. 129 130The image data to be compressed is supplied to jpeg_write_scanlines() from 131in-memory buffers. If the application is doing file-to-file compression, 132reading image data from the source file is the application's responsibility. 133The library emits compressed data by calling a "data destination manager", 134which typically will write the data into a file; but the application can 135provide its own destination manager to do something else. 136 137Similarly, the rough outline of a JPEG decompression operation is: 138 139 Allocate and initialize a JPEG decompression object 140 Specify the source of the compressed data (eg, a file) 141 Call jpeg_read_header() to obtain image info 142 Set parameters for decompression 143 jpeg_start_decompress(...); 144 while (scan lines remain to be read) 145 jpeg_read_scanlines(...); 146 jpeg_finish_decompress(...); 147 Release the JPEG decompression object 148 149This is comparable to the compression outline except that reading the 150datastream header is a separate step. This is helpful because information 151about the image's size, colorspace, etc is available when the application 152selects decompression parameters. For example, the application can choose an 153output scaling ratio that will fit the image into the available screen size. 154 155The decompression library obtains compressed data by calling a data source 156manager, which typically will read the data from a file; but other behaviors 157can be obtained with a custom source manager. Decompressed data is delivered 158into in-memory buffers passed to jpeg_read_scanlines(). 159 160It is possible to abort an incomplete compression or decompression operation 161by calling jpeg_abort(); or, if you do not need to retain the JPEG object, 162simply release it by calling jpeg_destroy(). 163 164JPEG compression and decompression objects are two separate struct types. 165However, they share some common fields, and certain routines such as 166jpeg_destroy() can work on either type of object. 167 168The JPEG library has no static variables: all state is in the compression 169or decompression object. Therefore it is possible to process multiple 170compression and decompression operations concurrently, using multiple JPEG 171objects. 172 173Both compression and decompression can be done in an incremental memory-to- 174memory fashion, if suitable source/destination managers are used. However, 175there are some restrictions on the processing that can be done in this mode. 176See the section on "I/O suspension" for more details. 177 178 179BASIC LIBRARY USAGE 180=================== 181 182Data formats 183------------ 184 185Before diving into procedural details, it is helpful to understand the 186image data format that the JPEG library expects or returns. 187 188The standard input image format is a rectangular array of pixels, with each 189pixel having the same number of "component" values (color channels). You 190must specify how many components there are and the colorspace interpretation 191of the components. Most applications will use RGB data (three components 192per pixel) or grayscale data (one component per pixel). 193 194Note that there is no provision for colormapped input. You can feed in a 195colormapped image by expanding it to full-color format. However JPEG often 196doesn't work very well with colormapped source data, because of dithering 197noise. This is discussed in more detail in the JPEG FAQ and the other 198references mentioned in the README file. 199 200Pixels are stored by scanlines, with each scanline running from left to 201right. The component values for each pixel are adjacent in the row; for 202example, R,G,B,R,G,B,R,G,B,... for 24-bit RGB color. Each scanline is an 203array of data type JSAMPLE --- which is typically "unsigned char", unless 204you've changed jmorecfg.h. (You can also change the RGB pixel layout, say 205to B,G,R order, by modifying jmorecfg.h. But see the restrictions listed in 206that file before doing so.) 207 208A 2-D array of pixels is formed by making a list of pointers to the starts of 209scanlines; so the scanlines need not be physically adjacent in memory. Even 210if you process just one scanline at a time, you must make a one-element 211pointer array to serve this purpose. Pointers to JSAMPLE rows are of type 212JSAMPROW, and the pointer to the pointer array is of type JSAMPARRAY. 213 214The library accepts or supplies one or more complete scanlines per call. 215It is not possible to process part of a row at a time. Scanlines are always 216processed top-to-bottom. You can process an entire image in one call if you 217have it all in memory, but usually it's simplest to process one scanline at 218a time. 219 220For best results, source data values should have the precision specified by 221BITS_IN_JSAMPLE (normally 8 bits). For instance, if you choose to compress 222data that's only 6 bits/channel, you should left-justify each value in a 223byte before passing it to the compressor. If you need to compress data 224that has more than 8 bits/channel, compile with BITS_IN_JSAMPLE = 12. 225(See "Library compile-time options", later.) 226 227The data format returned by the decompressor is the same in all details, 228except that colormapped data is supported. If you request colormapped 229output then the returned data array contains a single JSAMPLE per pixel; 230its value is an index into a color map. The color map is represented as 231a 2-D JSAMPARRAY in which each row holds the values of one color component, 232that is, colormap[i][j] is the value of the i'th color component for pixel 233value (map index) j. Note that since the colormap indexes are stored in 234JSAMPLEs, the maximum number of colors is limited by the size of JSAMPLE 235(ie, at most 256 colors for an 8-bit JPEG library). 236 237 238Compression details 239------------------- 240 241Here we revisit the JPEG compression outline given in the overview. 242 2431. Allocate and initialize a JPEG compression object. 244 245A JPEG compression object is a "struct jpeg_compress_struct" (plus a bunch of 246subsidiary structures which are allocated via malloc(), but the application 247doesn't control those directly). This struct can be just a local variable in 248the calling routine, if a single routine is going to execute the whole JPEG 249compression sequence. Otherwise it can be static or allocated from malloc(). 250 251You will also need a structure representing a JPEG error handler. The part 252of this that the library cares about is a "struct jpeg_error_mgr". If you 253are providing your own error handler, you'll typically want to embed the 254jpeg_error_mgr struct in a larger structure; this is discussed later under 255"Error handling". For now we'll assume you are just using the default error 256handler. The default error handler will print JPEG error/warning messages 257on stderr, and it will call exit() if a fatal error occurs. 258 259You must initialize the error handler structure, store a pointer to it into 260the JPEG object's "err" field, and then call jpeg_create_compress() to 261initialize the rest of the JPEG object. 262 263Typical code for this step, if you are using the default error handler, is 264 265 struct jpeg_compress_struct cinfo; 266 struct jpeg_error_mgr jerr; 267 ... 268 cinfo.err = jpeg_std_error(&jerr); 269 jpeg_create_compress(&cinfo); 270 271jpeg_create_compress allocates a small amount of memory, so it could fail 272if you are out of memory. In that case it will exit via the error handler; 273that's why the error handler must be initialized first. 274 275 2762. Specify the destination for the compressed data (eg, a file). 277 278As previously mentioned, the JPEG library delivers compressed data to a 279"data destination" module. The library includes one data destination 280module which knows how to write to a stdio stream. You can use your own 281destination module if you want to do something else, as discussed later. 282 283If you use the standard destination module, you must open the target stdio 284stream beforehand. Typical code for this step looks like: 285 286 FILE * outfile; 287 ... 288 if ((outfile = fopen(filename, "wb")) == NULL) { 289 fprintf(stderr, "can't open %s\n", filename); 290 exit(1); 291 } 292 jpeg_stdio_dest(&cinfo, outfile); 293 294where the last line invokes the standard destination module. 295 296WARNING: it is critical that the binary compressed data be delivered to the 297output file unchanged. On non-Unix systems the stdio library may perform 298newline translation or otherwise corrupt binary data. To suppress this 299behavior, you may need to use a "b" option to fopen (as shown above), or use 300setmode() or another routine to put the stdio stream in binary mode. See 301cjpeg.c and djpeg.c for code that has been found to work on many systems. 302 303You can select the data destination after setting other parameters (step 3), 304if that's more convenient. You may not change the destination between 305calling jpeg_start_compress() and jpeg_finish_compress(). 306 307 3083. Set parameters for compression, including image size & colorspace. 309 310You must supply information about the source image by setting the following 311fields in the JPEG object (cinfo structure): 312 313 image_width Width of image, in pixels 314 image_height Height of image, in pixels 315 input_components Number of color channels (samples per pixel) 316 in_color_space Color space of source image 317 318The image dimensions are, hopefully, obvious. JPEG supports image dimensions 319of 1 to 64K pixels in either direction. The input color space is typically 320RGB or grayscale, and input_components is 3 or 1 accordingly. (See "Special 321color spaces", later, for more info.) The in_color_space field must be 322assigned one of the J_COLOR_SPACE enum constants, typically JCS_RGB or 323JCS_GRAYSCALE. 324 325JPEG has a large number of compression parameters that determine how the 326image is encoded. Most applications don't need or want to know about all 327these parameters. You can set all the parameters to reasonable defaults by 328calling jpeg_set_defaults(); then, if there are particular values you want 329to change, you can do so after that. The "Compression parameter selection" 330section tells about all the parameters. 331 332You must set in_color_space correctly before calling jpeg_set_defaults(), 333because the defaults depend on the source image colorspace. However the 334other three source image parameters need not be valid until you call 335jpeg_start_compress(). There's no harm in calling jpeg_set_defaults() more 336than once, if that happens to be convenient. 337 338Typical code for a 24-bit RGB source image is 339 340 cinfo.image_width = Width; /* image width and height, in pixels */ 341 cinfo.image_height = Height; 342 cinfo.input_components = 3; /* # of color components per pixel */ 343 cinfo.in_color_space = JCS_RGB; /* colorspace of input image */ 344 345 jpeg_set_defaults(&cinfo); 346 /* Make optional parameter settings here */ 347 348 3494. jpeg_start_compress(...); 350 351After you have established the data destination and set all the necessary 352source image info and other parameters, call jpeg_start_compress() to begin 353a compression cycle. This will initialize internal state, allocate working 354storage, and emit the first few bytes of the JPEG datastream header. 355 356Typical code: 357 358 jpeg_start_compress(&cinfo, TRUE); 359 360The "TRUE" parameter ensures that a complete JPEG interchange datastream 361will be written. This is appropriate in most cases. If you think you might 362want to use an abbreviated datastream, read the section on abbreviated 363datastreams, below. 364 365Once you have called jpeg_start_compress(), you may not alter any JPEG 366parameters or other fields of the JPEG object until you have completed 367the compression cycle. 368 369 3705. while (scan lines remain to be written) 371 jpeg_write_scanlines(...); 372 373Now write all the required image data by calling jpeg_write_scanlines() 374one or more times. You can pass one or more scanlines in each call, up 375to the total image height. In most applications it is convenient to pass 376just one or a few scanlines at a time. The expected format for the passed 377data is discussed under "Data formats", above. 378 379Image data should be written in top-to-bottom scanline order. The JPEG spec 380contains some weasel wording about how top and bottom are application-defined 381terms (a curious interpretation of the English language...) but if you want 382your files to be compatible with everyone else's, you WILL use top-to-bottom 383order. If the source data must be read in bottom-to-top order, you can use 384the JPEG library's virtual array mechanism to invert the data efficiently. 385Examples of this can be found in the sample application cjpeg. 386 387The library maintains a count of the number of scanlines written so far 388in the next_scanline field of the JPEG object. Usually you can just use 389this variable as the loop counter, so that the loop test looks like 390"while (cinfo.next_scanline < cinfo.image_height)". 391 392Code for this step depends heavily on the way that you store the source data. 393example.c shows the following code for the case of a full-size 2-D source 394array containing 3-byte RGB pixels: 395 396 JSAMPROW row_pointer[1]; /* pointer to a single row */ 397 int row_stride; /* physical row width in buffer */ 398 399 row_stride = image_width * 3; /* JSAMPLEs per row in image_buffer */ 400 401 while (cinfo.next_scanline < cinfo.image_height) { 402 row_pointer[0] = & image_buffer[cinfo.next_scanline * row_stride]; 403 jpeg_write_scanlines(&cinfo, row_pointer, 1); 404 } 405 406jpeg_write_scanlines() returns the number of scanlines actually written. 407This will normally be equal to the number passed in, so you can usually 408ignore the return value. It is different in just two cases: 409 * If you try to write more scanlines than the declared image height, 410 the additional scanlines are ignored. 411 * If you use a suspending data destination manager, output buffer overrun 412 will cause the compressor to return before accepting all the passed lines. 413 This feature is discussed under "I/O suspension", below. The normal 414 stdio destination manager will NOT cause this to happen. 415In any case, the return value is the same as the change in the value of 416next_scanline. 417 418 4196. jpeg_finish_compress(...); 420 421After all the image data has been written, call jpeg_finish_compress() to 422complete the compression cycle. This step is ESSENTIAL to ensure that the 423last bufferload of data is written to the data destination. 424jpeg_finish_compress() also releases working memory associated with the JPEG 425object. 426 427Typical code: 428 429 jpeg_finish_compress(&cinfo); 430 431If using the stdio destination manager, don't forget to close the output 432stdio stream if necessary. 433 434If you have requested a multi-pass operating mode, such as Huffman code 435optimization, jpeg_finish_compress() will perform the additional passes using 436data buffered by the first pass. In this case jpeg_finish_compress() may take 437quite a while to complete. With the default compression parameters, this will 438not happen. 439 440It is an error to call jpeg_finish_compress() before writing the necessary 441total number of scanlines. If you wish to abort compression, call 442jpeg_abort() as discussed below. 443 444After completing a compression cycle, you may dispose of the JPEG object 445as discussed next, or you may use it to compress another image. In that case 446return to step 2, 3, or 4 as appropriate. If you do not change the 447destination manager, the new datastream will be written to the same target. 448If you do not change any JPEG parameters, the new datastream will be written 449with the same parameters as before. Note that you can change the input image 450dimensions freely between cycles, but if you change the input colorspace, you 451should call jpeg_set_defaults() to adjust for the new colorspace; and then 452you'll need to repeat all of step 3. 453 454 4557. Release the JPEG compression object. 456 457When you are done with a JPEG compression object, destroy it by calling 458jpeg_destroy_compress(). This will free all subsidiary memory. Or you can 459call jpeg_destroy() which works for either compression or decompression 460objects --- this may be more convenient if you are sharing code between 461compression and decompression cases. (Actually, these routines are equivalent 462except for the declared type of the passed pointer. To avoid gripes from 463ANSI C compilers, pass a j_common_ptr to jpeg_destroy().) 464 465If you allocated the jpeg_compress_struct structure from malloc(), freeing 466it is your responsibility --- jpeg_destroy() won't. Ditto for the error 467handler structure. 468 469Typical code: 470 471 jpeg_destroy_compress(&cinfo); 472 473 4748. Aborting. 475 476If you decide to abort a compression cycle before finishing, you can clean up 477in either of two ways: 478 479* If you don't need the JPEG object any more, just call 480 jpeg_destroy_compress() or jpeg_destroy() to release memory. This is 481 legitimate at any point after calling jpeg_create_compress() --- in fact, 482 it's safe even if jpeg_create_compress() fails. 483 484* If you want to re-use the JPEG object, call jpeg_abort_compress(), or 485 jpeg_abort() which works on both compression and decompression objects. 486 This will return the object to an idle state, releasing any working memory. 487 jpeg_abort() is allowed at any time after successful object creation. 488 489Note that cleaning up the data destination, if required, is your 490responsibility. 491 492 493Decompression details 494--------------------- 495 496Here we revisit the JPEG decompression outline given in the overview. 497 4981. Allocate and initialize a JPEG decompression object. 499 500This is just like initialization for compression, as discussed above, 501except that the object is a "struct jpeg_decompress_struct" and you 502call jpeg_create_decompress(). Error handling is exactly the same. 503 504Typical code: 505 506 struct jpeg_decompress_struct cinfo; 507 struct jpeg_error_mgr jerr; 508 ... 509 cinfo.err = jpeg_std_error(&jerr); 510 jpeg_create_decompress(&cinfo); 511 512(Both here and in the IJG code, we usually use variable name "cinfo" for 513both compression and decompression objects.) 514 515 5162. Specify the source of the compressed data (eg, a file). 517 518As previously mentioned, the JPEG library reads compressed data from a "data 519source" module. The library includes one data source module which knows how 520to read from a stdio stream. You can use your own source module if you want 521to do something else, as discussed later. 522 523If you use the standard source module, you must open the source stdio stream 524beforehand. Typical code for this step looks like: 525 526 FILE * infile; 527 ... 528 if ((infile = fopen(filename, "rb")) == NULL) { 529 fprintf(stderr, "can't open %s\n", filename); 530 exit(1); 531 } 532 jpeg_stdio_src(&cinfo, infile); 533 534where the last line invokes the standard source module. 535 536WARNING: it is critical that the binary compressed data be read unchanged. 537On non-Unix systems the stdio library may perform newline translation or 538otherwise corrupt binary data. To suppress this behavior, you may need to use 539a "b" option to fopen (as shown above), or use setmode() or another routine to 540put the stdio stream in binary mode. See cjpeg.c and djpeg.c for code that 541has been found to work on many systems. 542 543You may not change the data source between calling jpeg_read_header() and 544jpeg_finish_decompress(). If you wish to read a series of JPEG images from 545a single source file, you should repeat the jpeg_read_header() to 546jpeg_finish_decompress() sequence without reinitializing either the JPEG 547object or the data source module; this prevents buffered input data from 548being discarded. 549 550 5513. Call jpeg_read_header() to obtain image info. 552 553Typical code for this step is just 554 555 jpeg_read_header(&cinfo, TRUE); 556 557This will read the source datastream header markers, up to the beginning 558of the compressed data proper. On return, the image dimensions and other 559info have been stored in the JPEG object. The application may wish to 560consult this information before selecting decompression parameters. 561 562More complex code is necessary if 563 * A suspending data source is used --- in that case jpeg_read_header() 564 may return before it has read all the header data. See "I/O suspension", 565 below. The normal stdio source manager will NOT cause this to happen. 566 * Abbreviated JPEG files are to be processed --- see the section on 567 abbreviated datastreams. Standard applications that deal only in 568 interchange JPEG files need not be concerned with this case either. 569 570It is permissible to stop at this point if you just wanted to find out the 571image dimensions and other header info for a JPEG file. In that case, 572call jpeg_destroy() when you are done with the JPEG object, or call 573jpeg_abort() to return it to an idle state before selecting a new data 574source and reading another header. 575 576 5774. Set parameters for decompression. 578 579jpeg_read_header() sets appropriate default decompression parameters based on 580the properties of the image (in particular, its colorspace). However, you 581may well want to alter these defaults before beginning the decompression. 582For example, the default is to produce full color output from a color file. 583If you want colormapped output you must ask for it. Other options allow the 584returned image to be scaled and allow various speed/quality tradeoffs to be 585selected. "Decompression parameter selection", below, gives details. 586 587If the defaults are appropriate, nothing need be done at this step. 588 589Note that all default values are set by each call to jpeg_read_header(). 590If you reuse a decompression object, you cannot expect your parameter 591settings to be preserved across cycles, as you can for compression. 592You must adjust parameter values each time. 593 594 5955. jpeg_start_decompress(...); 596 597Once the parameter values are satisfactory, call jpeg_start_decompress() to 598begin decompression. This will initialize internal state, allocate working 599memory, and prepare for returning data. 600 601Typical code is just 602 603 jpeg_start_decompress(&cinfo); 604 605If you have requested a multi-pass operating mode, such as 2-pass color 606quantization, jpeg_start_decompress() will do everything needed before data 607output can begin. In this case jpeg_start_decompress() may take quite a while 608to complete. With a single-scan (fully interleaved) JPEG file and default 609decompression parameters, this will not happen; jpeg_start_decompress() will 610return quickly. 611 612After this call, the final output image dimensions, including any requested 613scaling, are available in the JPEG object; so is the selected colormap, if 614colormapped output has been requested. Useful fields include 615 616 output_width image width and height, as scaled 617 output_height 618 out_color_components # of color components in out_color_space 619 output_components # of color components returned per pixel 620 colormap the selected colormap, if any 621 actual_number_of_colors number of entries in colormap 622 623output_components is 1 (a colormap index) when quantizing colors; otherwise it 624equals out_color_components. It is the number of JSAMPLE values that will be 625emitted per pixel in the output arrays. 626 627Typically you will need to allocate data buffers to hold the incoming image. 628You will need output_width * output_components JSAMPLEs per scanline in your 629output buffer, and a total of output_height scanlines will be returned. 630 631Note: if you are using the JPEG library's internal memory manager to allocate 632data buffers (as djpeg does), then the manager's protocol requires that you 633request large buffers *before* calling jpeg_start_decompress(). This is a 634little tricky since the output_XXX fields are not normally valid then. You 635can make them valid by calling jpeg_calc_output_dimensions() after setting the 636relevant parameters (scaling, output color space, and quantization flag). 637 638 6396. while (scan lines remain to be read) 640 jpeg_read_scanlines(...); 641 642Now you can read the decompressed image data by calling jpeg_read_scanlines() 643one or more times. At each call, you pass in the maximum number of scanlines 644to be read (ie, the height of your working buffer); jpeg_read_scanlines() 645will return up to that many lines. The return value is the number of lines 646actually read. The format of the returned data is discussed under "Data 647formats", above. 648 649Image data is returned in top-to-bottom scanline order. If you must write 650out the image in bottom-to-top order, you can use the JPEG library's virtual 651array mechanism to invert the data efficiently. Examples of this can be 652found in the sample application djpeg. 653 654The library maintains a count of the number of scanlines returned so far 655in the output_scanline field of the JPEG object. Usually you can just use 656this variable as the loop counter, so that the loop test looks like 657"while (cinfo.output_scanline < cinfo.output_height)". (Note that the test 658should NOT be against image_height, unless you never use scaling. The 659image_height field is the height of the original unscaled image.) 660The return value always equals the change in the value of output_scanline. 661 662If you don't use a suspending data source, it is safe to assume that 663jpeg_read_scanlines() reads at least one scanline per call, until the 664bottom of the image has been reached. If you use a buffer larger than one 665scanline, it is NOT safe to assume that jpeg_read_scanlines() fills it. 666(The current implementation won't return more than cinfo.rec_outbuf_height 667scanlines per call, no matter how large a buffer you pass.) So you must 668always provide a loop that calls jpeg_read_scanlines() repeatedly until 669the whole image has been read. 670 671 6727. jpeg_finish_decompress(...); 673 674After all the image data has been read, call jpeg_finish_decompress() to 675complete the decompression cycle. This causes working memory associated 676with the JPEG object to be released. 677 678Typical code: 679 680 jpeg_finish_decompress(&cinfo); 681 682If using the stdio source manager, don't forget to close the source stdio 683stream if necessary. 684 685It is an error to call jpeg_finish_decompress() before reading the correct 686total number of scanlines. If you wish to abort compression, call 687jpeg_abort() as discussed below. 688 689After completing a decompression cycle, you may dispose of the JPEG object as 690discussed next, or you may use it to decompress another image. In that case 691return to step 2 or 3 as appropriate. If you do not change the source 692manager, the next image will be read from the same source. 693 694 6958. Release the JPEG decompression object. 696 697When you are done with a JPEG decompression object, destroy it by calling 698jpeg_destroy_decompress() or jpeg_destroy(). The previous discussion of 699destroying compression objects applies here too. 700 701Typical code: 702 703 jpeg_destroy_decompress(&cinfo); 704 705 7069. Aborting. 707 708You can abort a decompression cycle by calling jpeg_destroy_decompress() or 709jpeg_destroy() if you don't need the JPEG object any more, or 710jpeg_abort_decompress() or jpeg_abort() if you want to reuse the object. 711The previous discussion of aborting compression cycles applies here too. 712 713 714Mechanics of usage: include files, linking, etc 715----------------------------------------------- 716 717Applications using the JPEG library should include the header file jpeglib.h 718to obtain declarations of data types and routines. Before including 719jpeglib.h, include system headers that define at least the typedefs FILE and 720size_t. On ANSI-conforming systems, including <stdio.h> is sufficient; on 721older Unix systems, you may need <sys/types.h> to define size_t. 722 723If the application needs to refer to individual JPEG library error codes, also 724include jerror.h to define those symbols. 725 726jpeglib.h indirectly includes the files jconfig.h and jmorecfg.h. If you are 727installing the JPEG header files in a system directory, you will want to 728install all four files: jpeglib.h, jerror.h, jconfig.h, jmorecfg.h. 729 730The most convenient way to include the JPEG code into your executable program 731is to prepare a library file ("libjpeg.a", or a corresponding name on non-Unix 732machines) and reference it at your link step. If you use only half of the 733library (only compression or only decompression), only that much code will be 734included from the library, unless your linker is hopelessly brain-damaged. 735The supplied makefiles build libjpeg.a automatically (see install.doc). 736 737On some systems your application may need to set up a signal handler to ensure 738that temporary files are deleted if the program is interrupted. This is most 739critical if you are on MS-DOS and use the jmemdos.c memory manager back end; 740it will try to grab extended memory for temp files, and that space will NOT be 741freed automatically. See cjpeg.c or djpeg.c for an example signal handler. 742 743It may be worth pointing out that the core JPEG library does not actually 744require the stdio library: only the default source/destination managers and 745error handler need it. You can use the library in a stdio-less environment 746if you replace those modules and use jmemnobs.c (or another memory manager of 747your own devising). More info about the minimum system library requirements 748may be found in jinclude.h. 749 750 751ADVANCED FEATURES 752================= 753 754Compression parameter selection 755------------------------------- 756 757This section describes all the optional parameters you can set for JPEG 758compression, as well as the "helper" routines provided to assist in this 759task. Proper setting of some parameters requires detailed understanding 760of the JPEG standard; if you don't know what a parameter is for, it's best 761not to mess with it! See REFERENCES in the README file for pointers to 762more info about JPEG. 763 764It's a good idea to call jpeg_set_defaults() first, even if you plan to set 765all the parameters; that way your code is more likely to work with future JPEG 766libraries that have additional parameters. For the same reason, we recommend 767you use a helper routine where one is provided, in preference to twiddling 768cinfo fields directly. 769 770The helper routines are: 771 772jpeg_set_defaults (j_compress_ptr cinfo) 773 This routine sets all JPEG parameters to reasonable defaults, using 774 only the input image's color space (field in_color_space, which must 775 already be set in cinfo). Many applications will only need to use 776 this routine and perhaps jpeg_set_quality(). 777 778jpeg_set_colorspace (j_compress_ptr cinfo, J_COLOR_SPACE colorspace) 779 Sets the JPEG file's colorspace (field jpeg_color_space) as specified, 780 and sets other color-space-dependent parameters appropriately. See 781 "Special color spaces", below, before using this. A large number of 782 parameters, including all per-component parameters, are set by this 783 routine; if you want to twiddle individual parameters you should call 784 jpeg_set_colorspace() before rather than after. 785 786jpeg_default_colorspace (j_compress_ptr cinfo) 787 Selects an appropriate JPEG colorspace based on cinfo->in_color_space, 788 and calls jpeg_set_colorspace(). This is actually a subroutine of 789 jpeg_set_defaults(). It's broken out in case you want to change 790 just the colorspace-dependent JPEG parameters. 791 792jpeg_set_quality (j_compress_ptr cinfo, int quality, boolean force_baseline) 793 Constructs JPEG quantization tables appropriate for the indicated 794 quality setting. The quality value is expressed on the 0..100 scale 795 recommended by IJG (cjpeg's "-quality" switch uses this routine). 796 Note that the exact mapping from quality values to tables may change 797 in future IJG releases as more is learned about DCT quantization. 798 If the force_baseline parameter is TRUE, then the quantization table 799 entries are constrained to the range 1..255 for full JPEG baseline 800 compatibility. In the current implementation, this only makes a 801 difference for quality settings below 25, and it effectively prevents 802 very small/low quality files from being generated. The IJG decoder 803 is capable of reading the non-baseline files generated at low quality 804 settings when force_baseline is FALSE, but other decoders may not be. 805 806jpeg_set_linear_quality (j_compress_ptr cinfo, int scale_factor, 807 boolean force_baseline) 808 Same as jpeg_set_quality() except that the generated tables are the 809 sample tables given in the JPEC spec section K.1, multiplied by the 810 specified scale factor (which is expressed as a percentage; thus 811 scale_factor = 100 reproduces the spec's tables). Note that larger 812 scale factors give lower quality. This entry point is useful for 813 conforming to the Adobe PostScript DCT conventions, but we do not 814 recommend linear scaling as a user-visible quality scale otherwise. 815 force_baseline again constrains the computed table entries to 1..255. 816 817int jpeg_quality_scaling (int quality) 818 Converts a value on the IJG-recommended quality scale to a linear 819 scaling percentage. Note that this routine may change or go away 820 in future releases --- IJG may choose to adopt a scaling method that 821 can't be expressed as a simple scalar multiplier, in which case the 822 premise of this routine collapses. Caveat user. 823 824jpeg_add_quant_table (j_compress_ptr cinfo, int which_tbl, 825 const unsigned int *basic_table, 826 int scale_factor, boolean force_baseline)); 827 Allows an arbitrary quantization table to be created. which_tbl 828 indicates which table slot to fill. basic_table points to an array 829 of 64 unsigned ints given in JPEG zigzag order. These values are 830 multiplied by scale_factor/100 and then clamped to the range 1..65535 831 (or to 1..255 if force_baseline is TRUE). 832 833 834Compression parameters (cinfo fields) include: 835 836boolean optimize_coding 837 TRUE causes the compressor to compute optimal Huffman coding tables 838 for the image. This requires an extra pass over the data and 839 therefore costs a good deal of space and time. The default is 840 FALSE, which tells the compressor to use the supplied or default 841 Huffman tables. In most cases optimal tables save only a few percent 842 of file size compared to the default tables. Note that when this is 843 TRUE, you need not supply Huffman tables at all, and any you do 844 supply will be overwritten. 845 846int smoothing_factor 847 If non-zero, the input image is smoothed; the value should be 1 for 848 minimal smoothing to 100 for maximum smoothing. Consult jcsample.c 849 for details of the smoothing algorithm. The default is zero. 850 851J_DCT_METHOD dct_method 852 Selects the algorithm used for the DCT step. Choices are: 853 JDCT_ISLOW: slow but accurate integer algorithm 854 JDCT_IFAST: faster, less accurate integer method 855 JDCT_FLOAT: floating-point method 856 JDCT_DEFAULT: default method (normally JDCT_ISLOW) 857 JDCT_FASTEST: fastest method (normally JDCT_IFAST) 858 The floating-point method is the most accurate, but may give slightly 859 different results on different machines due to varying roundoff 860 behavior. The integer methods should give the same results on all 861 machines. On machines with sufficiently fast FP hardware, the 862 floating-point method may also be the fastest. The IFAST method is 863 considerably less accurate than the other two; its use is not 864 recommended if high quality is a concern. JDCT_DEFAULT and 865 JDCT_FASTEST are macros configurable by each installation. 866 867unsigned int restart_interval 868int restart_in_rows 869 To emit restart markers in the JPEG file, set one of these nonzero. 870 Set restart_interval to specify the exact interval in MCU blocks. 871 Set restart_in_rows to specify the interval in MCU rows. (If 872 restart_in_rows is not 0, then restart_interval is set after the 873 image width in MCUs is computed.) Defaults are zero (no restarts). 874 875J_COLOR_SPACE jpeg_color_space 876int num_components 877 The JPEG color space and corresponding number of components; see 878 "Special color spaces", below, for more info. We recommend using 879 jpeg_set_color_space() if you want to change these. 880 881boolean write_JFIF_header 882 If TRUE, a JFIF APP0 marker is emitted. jpeg_set_defaults() and 883 jpeg_set_colorspace() set this TRUE if a JFIF-legal JPEG color space 884 (ie, YCbCr or grayscale) is selected, otherwise FALSE. 885 886UINT8 density_unit 887UINT16 X_density 888UINT16 Y_density 889 The resolution information to be written into the JFIF marker; 890 not used otherwise. density_unit may be 0 for unknown, 891 1 for dots/inch, or 2 for dots/cm. The default values are 0,1,1 892 indicating square pixels of unknown size. 893 894boolean write_Adobe_marker 895 If TRUE, an Adobe APP14 marker is emitted. jpeg_set_defaults() and 896 jpeg_set_colorspace() set this TRUE if JPEG color space RGB, CMYK, 897 or YCCK is selected, otherwise FALSE. It is generally a bad idea 898 to set both write_JFIF_header and write_Adobe_marker. In fact, 899 you probably shouldn't change the default settings at all --- the 900 default behavior ensures that the JPEG file's color space can be 901 recognized by the decoder. 902 903JQUANT_TBL * quant_tbl_ptrs[NUM_QUANT_TBLS] 904 Pointers to coefficient quantization tables, one per table slot, 905 or NULL if no table is defined for a slot. Usually these should 906 be set via one of the above helper routines; jpeg_add_quant_table() 907 is general enough to define any quantization table. The other 908 routines will set up table slot 0 for luminance quality and table 909 slot 1 for chrominance. 910 911JHUFF_TBL * dc_huff_tbl_ptrs[NUM_HUFF_TBLS] 912JHUFF_TBL * ac_huff_tbl_ptrs[NUM_HUFF_TBLS] 913 Pointers to Huffman coding tables, one per table slot, or NULL if 914 no table is defined for a slot. Slots 0 and 1 are filled with the 915 JPEG sample tables by jpeg_set_defaults(). If you need to allocate 916 more table structures, jpeg_alloc_huff_table() may be used. 917 Note that optimal Huffman tables can be computed for an image 918 by setting optimize_coding, as discussed above; there's seldom 919 any need to mess with providing your own Huffman tables. 920 921There are some additional cinfo fields which are not documented here 922because you currently can't change them; for example, you can't set 923arith_code TRUE because arithmetic coding is unsupported. 924 925 926Per-component parameters are stored in the struct cinfo.comp_info[i] for 927component number i. Note that components here refer to components of the 928JPEG color space, *not* the source image color space. A suitably large 929comp_info[] array is allocated by jpeg_set_defaults(); if you choose not 930to use that routine, it's up to you to allocate the array. 931 932int component_id 933 The one-byte identifier code to be recorded in the JPEG file for 934 this component. For the standard color spaces, we recommend you 935 leave the default values alone. 936 937int h_samp_factor 938int v_samp_factor 939 Horizontal and vertical sampling factors for the component; must 940 be 1..4 according to the JPEG standard. Note that larger sampling 941 factors indicate a higher-resolution component; many people find 942 this behavior quite unintuitive. The default values are 2,2 for 943 luminance components and 1,1 for chrominance components, except 944 for grayscale where 1,1 is used. 945 946int quant_tbl_no 947 Quantization table number for component. The default value is 948 0 for luminance components and 1 for chrominance components. 949 950int dc_tbl_no 951int ac_tbl_no 952 DC and AC entropy coding table numbers. The default values are 953 0 for luminance components and 1 for chrominance components. 954 955int component_index 956 Must equal the component's index in comp_info[]. 957 958 959Decompression parameter selection 960--------------------------------- 961 962Decompression parameter selection is somewhat simpler than compression 963parameter selection, since all of the JPEG internal parameters are 964recorded in the source file and need not be supplied by the application. 965(Unless you are working with abbreviated files, in which case see 966"Abbreviated datastreams", below.) Decompression parameters control 967the postprocessing done on the image to deliver it in a format suitable 968for the application's use. Many of the parameters control speed/quality 969tradeoffs, in which faster decompression may be obtained at the price of 970a poorer-quality image. The defaults select the highest quality (slowest) 971processing. 972 973The following fields in the JPEG object are set by jpeg_read_header() and 974may be useful to the application in choosing decompression parameters: 975 976JDIMENSION image_width Width and height of image 977JDIMENSION image_height 978int num_components Number of color components 979J_COLOR_SPACE jpeg_color_space Colorspace of image 980boolean saw_JFIF_marker TRUE if a JFIF APP0 marker was seen 981 UINT8 density_unit Resolution data from JFIF marker 982 UINT16 X_density 983 UINT16 Y_density 984boolean saw_Adobe_marker TRUE if an Adobe APP14 marker was seen 985 UINT8 Adobe_transform Color transform code from Adobe marker 986 987The JPEG color space, unfortunately, is something of a guess since the JPEG 988standard proper does not provide a way to record it. In practice most files 989adhere to the JFIF or Adobe conventions, and the decoder will recognize these 990correctly. See "Special color spaces", below, for more info. 991 992 993The decompression parameters that determine the basic properties of the 994returned image are: 995 996J_COLOR_SPACE out_color_space 997 Output color space. jpeg_read_header() sets an appropriate default 998 based on jpeg_color_space; typically it will be RGB or grayscale. 999 The application can change this field to request output in a different 1000 colorspace. For example, set it to JCS_GRAYSCALE to get grayscale 1001 output from a color file. (This is useful for previewing: grayscale 1002 output is faster than full color since the color components need not 1003 be processed.) Note that not all possible color space transforms are 1004 currently implemented; you may need to extend jdcolor.c if you want an 1005 unusual conversion. 1006 1007unsigned int scale_num, scale_denom 1008 Scale the image by the fraction scale_num/scale_denom. Default is 1009 1/1, or no scaling. Currently, the only supported scaling ratios 1010 are 1/1, 1/2, 1/4, and 1/8. (The library design allows for arbitrary 1011 scaling ratios but this is not likely to be implemented any time soon.) 1012 Smaller scaling ratios permit significantly faster decoding since 1013 fewer pixels need be processed and a simpler IDCT method can be used. 1014 1015boolean quantize_colors 1016 If set TRUE, colormapped output will be delivered. Default is FALSE, 1017 meaning that full-color output will be delivered. 1018 1019The next three parameters are relevant only if quantize_colors is TRUE. 1020 1021int desired_number_of_colors 1022 Maximum number of colors to use in generating a library-supplied color 1023 map (the actual number of colors is returned in a different field). 1024 Default 256. Ignored when the application supplies its own color map. 1025 1026boolean two_pass_quantize 1027 If TRUE, an extra pass over the image is made to select a custom color 1028 map for the image. This usually looks a lot better than the one-size- 1029 fits-all colormap that is used otherwise. Default is TRUE. Ignored 1030 when the application supplies its own color map. 1031 1032J_DITHER_MODE dither_mode 1033 Selects color dithering method. Supported values are: 1034 JDITHER_NONE no dithering: fast, very low quality 1035 JDITHER_ORDERED ordered dither: moderate speed and quality 1036 JDITHER_FS Floyd-Steinberg dither: slow, high quality 1037 Default is JDITHER_FS. (At present, ordered dither is implemented 1038 only in the single-pass, standard-colormap case. If you ask for 1039 ordered dither when two_pass_quantize is TRUE or when you supply 1040 an external color map, you'll get F-S dithering.) 1041 1042When quantize_colors is TRUE, the target color map is described by the next 1043two fields. colormap is set to NULL by jpeg_read_header(). The application 1044can supply a color map by setting colormap non-NULL and setting 1045actual_number_of_colors to the map size. Otherwise, jpeg_start_decompress() 1046selects a suitable color map and sets these two fields itself. 1047[Implementation restriction: at present, an externally supplied colormap is 1048only accepted for 3-component output color spaces.] 1049 1050JSAMPARRAY colormap 1051 The color map, represented as a 2-D pixel array of out_color_components 1052 rows and actual_number_of_colors columns. Ignored if not quantizing. 1053 1054int actual_number_of_colors 1055 The number of colors in the color map. 1056 1057Additional decompression parameters that the application may set include: 1058 1059J_DCT_METHOD dct_method 1060 Selects the algorithm used for the DCT step. Choices are the same 1061 as described above for compression. 1062 1063boolean do_fancy_upsampling 1064 If TRUE, do careful upsampling of chroma components. If FALSE, 1065 a faster but sloppier method is used. Default is TRUE. The visual 1066 impact of the sloppier method is often very small. 1067 1068 1069The output image dimensions are given by the following fields. These are 1070computed from the source image dimensions and the decompression parameters 1071by jpeg_start_decompress(). You can also call jpeg_calc_output_dimensions() 1072to obtain the values that will result from the current parameter settings. 1073This can be useful if you are trying to pick a scaling ratio that will get 1074close to a desired target size. It's also important if you are using the 1075JPEG library's memory manager to allocate output buffer space, because you 1076are supposed to request such buffers *before* jpeg_start_decompress(). 1077 1078JDIMENSION output_width Actual dimensions of output image. 1079JDIMENSION output_height 1080int out_color_components Number of color components in out_color_space. 1081int output_components Number of color components returned. 1082int rec_outbuf_height Recommended height of scanline buffer. 1083 1084When quantizing colors, output_components is 1, indicating a single color map 1085index per pixel. Otherwise it equals out_color_components. The output arrays 1086are required to be output_width * output_components JSAMPLEs wide. 1087 1088rec_outbuf_height is the recommended minimum height (in scanlines) of the 1089buffer passed to jpeg_read_scanlines(). If the buffer is smaller, the 1090library will still work, but time will be wasted due to unnecessary data 1091copying. In high-quality modes, rec_outbuf_height is always 1, but some 1092faster, lower-quality modes set it to larger values (typically 2 to 4). 1093If you are going to ask for a high-speed processing mode, you may as well 1094go to the trouble of honoring rec_outbuf_height so as to avoid data copying. 1095 1096 1097Special color spaces 1098-------------------- 1099 1100The JPEG standard itself is "color blind" and doesn't specify any particular 1101color space. It is customary to convert color data to a luminance/chrominance 1102color space before compressing, since this permits greater compression. The 1103existing de-facto JPEG file format standards specify YCbCr or grayscale data 1104(JFIF), or grayscale, RGB, YCbCr, CMYK, or YCCK (Adobe). For special 1105applications such as multispectral images, other color spaces can be used, 1106but it must be understood that such files will be unportable. 1107 1108The JPEG library can handle the most common colorspace conversions (namely 1109RGB <=> YCbCr and CMYK <=> YCCK). It can also deal with data of an unknown 1110color space, passing it through without conversion. If you deal extensively 1111with an unusual color space, you can easily extend the library to understand 1112additional color spaces and perform appropriate conversions. 1113 1114For compression, the source data's color space is specified by field 1115in_color_space. This is transformed to the JPEG file's color space given 1116by jpeg_color_space. jpeg_set_defaults() chooses a reasonable JPEG color 1117space depending on in_color_space, but you can override this by calling 1118jpeg_set_colorspace(). Of course you must select a supported transformation. 1119jccolor.c currently supports the following transformations: 1120 RGB => YCbCr 1121 RGB => GRAYSCALE 1122 YCbCr => GRAYSCALE 1123 CMYK => YCCK 1124plus the null transforms: GRAYSCALE => GRAYSCALE, RGB => RGB, 1125YCbCr => YCbCr, CMYK => CMYK, YCCK => YCCK, and UNKNOWN => UNKNOWN. 1126 1127The de-facto file format standards (JFIF and Adobe) specify APPn markers that 1128indicate the color space of the JPEG file. It is important to ensure that 1129these are written correctly, or omitted if the JPEG file's color space is not 1130one of the ones supported by the de-facto standards. jpeg_set_colorspace() 1131will set the compression parameters to include or omit the APPn markers 1132properly, so long as it is told the truth about the JPEG color space. 1133For example, if you are writing some random 3-component color space without 1134conversion, don't try to fake out the library by setting in_color_space and 1135jpeg_color_space to JCS_YCbCr; use JCS_UNKNOWN. You may want to write an 1136APPn marker of your own devising to identify the colorspace --- see "Special 1137markers", below. 1138 1139When told that the color space is UNKNOWN, the library will default to using 1140luminance-quality compression parameters for all color components. You may 1141well want to change these parameters. See the source code for 1142jpeg_set_colorspace(), in jcparam.c, for details. 1143 1144For decompression, the JPEG file's color space is given in jpeg_color_space, 1145and this is transformed to the output color space out_color_space. 1146jpeg_read_header's setting of jpeg_color_space can be relied on if the file 1147conforms to JFIF or Adobe conventions, but otherwise it is no better than a 1148guess. If you know the JPEG file's color space for certain, you can override 1149jpeg_read_header's guess by setting jpeg_color_space. jpeg_read_header also 1150selects a default output color space based on (its guess of) jpeg_color_space; 1151set out_color_space to override this. Again, you must select a supported 1152transformation. jdcolor.c currently supports 1153 YCbCr => GRAYSCALE 1154 YCbCr => RGB 1155 YCCK => CMYK 1156as well as the null transforms. 1157 1158The two-pass color quantizer, jquant2.c, is specialized to handle RGB data 1159(it weights distances appropriately for RGB colors). You'll need to modify 1160the code if you want to use it for non-RGB output color spaces. Note that 1161jquant2.c is used to map to an application-supplied colormap as well as for 1162the normal two-pass colormap selection process. 1163 1164CAUTION: it appears that Adobe Photoshop writes inverted data in CMYK JPEG 1165files: 0 represents 100% ink coverage, rather than 0% ink as you'd expect. 1166This is arguably a bug in Photoshop, but if you need to work with Photoshop 1167CMYK files, you will have to deal with it in your application. We cannot 1168"fix" this in the library by inverting the data during the CMYK<=>YCCK 1169transform, because that would break other applications, notably Ghostscript. 1170Photoshop versions prior to 3.0 write EPS files containing JPEG-encoded CMYK 1171data in the same inverted-YCCK representation used in bare JPEG files, but 1172the surrounding PostScript code performs an inversion using the PS image 1173operator. I am told that Photoshop 3.0 will write uninverted YCCK in 1174EPS/JPEG files, and will omit the PS-level inversion. (But the data 1175polarity used in bare JPEG files will not change in 3.0.) In either case, 1176the JPEG library must not invert the data itself, or else Ghostscript would 1177read these EPS files incorrectly. 1178 1179 1180Error handling 1181-------------- 1182 1183When the default error handler is used, any error detected inside the JPEG 1184routines will cause a message to be printed on stderr, followed by exit(). 1185You can supply your own error handling routines to override this behavior 1186and to control the treatment of nonfatal warnings and trace/debug messages. 1187The file example.c illustrates the most common case, which is to have the 1188application regain control after an error rather than exiting. 1189 1190The JPEG library never writes any message directly; it always goes through 1191the error handling routines. Three classes of messages are recognized: 1192 * Fatal errors: the library cannot continue. 1193 * Warnings: the library can continue, but the data is corrupt, and a 1194 damaged output image is likely to result. 1195 * Trace/informational messages. These come with a trace level indicating 1196 the importance of the message; you can control the verbosity of the 1197 program by adjusting the maximum trace level that will be displayed. 1198 1199You may, if you wish, simply replace the entire JPEG error handling module 1200(jerror.c) with your own code. However, you can avoid code duplication by 1201only replacing some of the routines depending on the behavior you need. 1202This is accomplished by calling jpeg_std_error() as usual, but then overriding 1203some of the method pointers in the jpeg_error_mgr struct, as illustrated by 1204example.c. 1205 1206All of the error handling routines will receive a pointer to the JPEG object 1207(a j_common_ptr which points to either a jpeg_compress_struct or a 1208jpeg_decompress_struct; if you need to tell which, test the is_decompressor 1209field). This struct includes a pointer to the error manager struct in its 1210"err" field. Frequently, custom error handler routines will need to access 1211additional data which is not known to the JPEG library or the standard error 1212handler. The most convenient way to do this is to embed either the JPEG 1213object or the jpeg_error_mgr struct in a larger structure that contains 1214additional fields; then casting the passed pointer provides access to the 1215additional fields. Again, see example.c for one way to do it. 1216 1217The individual methods that you might wish to override are: 1218 1219error_exit (j_common_ptr cinfo) 1220 Receives control for a fatal error. Information sufficient to 1221 generate the error message has been stored in cinfo->err; call 1222 output_message to display it. Control must NOT return to the caller; 1223 generally this routine will exit() or longjmp() somewhere. 1224 Typically you would override this routine to get rid of the exit() 1225 default behavior. Note that if you continue processing, you should 1226 clean up the JPEG object with jpeg_abort() or jpeg_destroy(). 1227 1228output_message (j_common_ptr cinfo) 1229 Actual output of any JPEG message. Override this to send messages 1230 somewhere other than stderr. Note that this method does not know 1231 how to generate a message, only where to send it. 1232 1233format_message (j_common_ptr cinfo, char * buffer) 1234 Constructs a readable error message string based on the error info 1235 stored in cinfo->err. This method is called by output_message. Few 1236 applications should need to override this method. One possible 1237 reason for doing so is to implement dynamic switching of error message 1238 language. 1239 1240emit_message (j_common_ptr cinfo, int msg_level) 1241 Decide whether or not to emit a warning or trace message; if so, 1242 calls output_message. The main reason for overriding this method 1243 would be to abort on warnings. msg_level is -1 for warnings, 1244 0 and up for trace messages. 1245 1246Only error_exit() and emit_message() are called from the rest of the JPEG 1247library; the other two are internal to the error handler. 1248 1249The actual message texts are stored in an array of strings which is pointed to 1250by the field err->jpeg_message_table. The messages are numbered from 0 to 1251err->last_jpeg_message, and it is these code numbers that are used in the 1252JPEG library code. You could replace the message texts (for instance, with 1253messages in French or German) by changing the message table pointer. See 1254jerror.h for the default texts. CAUTION: this table will almost certainly 1255change or grow from one library version to the next. 1256 1257It may be useful for an application to add its own message texts that are 1258handled by the same mechanism. The error handler supports a second "add-on" 1259message table for this purpose. To define an addon table, set the pointer 1260err->addon_message_table and the message numbers err->first_addon_message and 1261err->last_addon_message. If you number the addon messages beginning at 1000 1262or so, you won't have to worry about conflicts with the library's built-in 1263messages. See the sample applications cjpeg/djpeg for an example of using 1264addon messages (the addon messages are defined in cderror.h). 1265 1266Actual invocation of the error handler is done via macros defined in jerror.h: 1267 ERREXITn(...) for fatal errors 1268 WARNMSn(...) for corrupt-data warnings 1269 TRACEMSn(...) for trace and informational messages. 1270These macros store the message code and any additional parameters into the 1271error handler struct, then invoke the error_exit() or emit_message() method. 1272The variants of each macro are for varying numbers of additional parameters. 1273The additional parameters are inserted into the generated message using 1274standard printf() format codes. 1275 1276See jerror.h and jerror.c for further details. 1277 1278 1279Compressed data handling (source and destination managers) 1280---------------------------------------------------------- 1281 1282The JPEG compression library sends its compressed data to a "destination 1283manager" module. The default destination manager just writes the data to a 1284stdio stream, but you can provide your own manager to do something else. 1285Similarly, the decompression library calls a "source manager" to obtain the 1286compressed data; you can provide your own source manager if you want the data 1287to come from somewhere other than a stdio stream. 1288 1289In both cases, compressed data is processed a bufferload at a time: the 1290destination or source manager provides a work buffer, and the library invokes 1291the manager only when the buffer is filled or emptied. (You could define a 1292one-character buffer to force the manager to be invoked for each byte, but 1293that would be rather inefficient.) The buffer's size and location are 1294controlled by the manager, not by the library. For example, if you desired to 1295decompress a JPEG datastream that was all in memory, you could just make the 1296buffer pointer and length point to the original data in memory. Then the 1297buffer-reload procedure would be invoked only if the decompressor ran off the 1298end of the datastream, which would indicate an erroneous datastream. 1299 1300The work buffer is defined as an array of datatype JOCTET, which is generally 1301"char" or "unsigned char". On a machine where char is not exactly 8 bits 1302wide, you must define JOCTET as a wider data type and then modify the data 1303source and destination modules to transcribe the work arrays into 8-bit units 1304on external storage. 1305 1306A data destination manager struct contains a pointer and count defining the 1307next byte to write in the work buffer and the remaining free space: 1308 1309 JOCTET * next_output_byte; /* => next byte to write in buffer */ 1310 size_t free_in_buffer; /* # of byte spaces remaining in buffer */ 1311 1312The library increments the pointer and decrements the count until the buffer 1313is filled. The manager's empty_output_buffer method must reset the pointer 1314and count. The manager is expected to remember the buffer's starting address 1315and total size in private fields not visible to the library. 1316 1317A data destination manager provides three methods: 1318 1319init_destination (j_compress_ptr cinfo) 1320 Initialize destination. This is called by jpeg_start_compress() 1321 before any data is actually written. It must initialize 1322 next_output_byte and free_in_buffer. free_in_buffer must be 1323 initialized to a positive value. 1324 1325empty_output_buffer (j_compress_ptr cinfo) 1326 This is called whenever the buffer has filled (free_in_buffer 1327 reaches zero). In typical applications, it should write out the 1328 *entire* buffer (use the saved start address and buffer length; 1329 ignore the current state of next_output_byte and free_in_buffer). 1330 Then reset the pointer & count to the start of the buffer, and 1331 return TRUE indicating that the buffer has been dumped. 1332 free_in_buffer must be set to a positive value when TRUE is 1333 returned. A FALSE return should only be used when I/O suspension is 1334 desired (this operating mode is discussed in the next section). 1335 1336term_destination (j_compress_ptr cinfo) 1337 Terminate destination --- called by jpeg_finish_compress() after all 1338 data has been written. In most applications, this must flush any 1339 data remaining in the buffer. Use either next_output_byte or 1340 free_in_buffer to determine how much data is in the buffer. 1341 1342term_destination() is NOT called by jpeg_abort() or jpeg_destroy(). If you 1343want the destination manager to be cleaned up during an abort, you must do it 1344yourself. 1345 1346You will also need code to create a jpeg_destination_mgr struct, fill in its 1347method pointers, and insert a pointer to the struct into the "dest" field of 1348the JPEG compression object. This can be done in-line in your setup code if 1349you like, but it's probably cleaner to provide a separate routine similar to 1350the jpeg_stdio_dest() routine of the supplied destination manager. 1351 1352Decompression source managers follow a parallel design, but with some 1353additional frammishes. The source manager struct contains a pointer and count 1354defining the next byte to read from the work buffer and the number of bytes 1355remaining: 1356 1357 const JOCTET * next_input_byte; /* => next byte to read from buffer */ 1358 size_t bytes_in_buffer; /* # of bytes remaining in buffer */ 1359 1360The library increments the pointer and decrements the count until the buffer 1361is emptied. The manager's fill_input_buffer method must reset the pointer and 1362count. In most applications, the manager must remember the buffer's starting 1363address and total size in private fields not visible to the library. 1364 1365A data source manager provides five methods: 1366 1367init_source (j_decompress_ptr cinfo) 1368 Initialize source. This is called by jpeg_read_header() before any 1369 data is actually read. Unlike init_destination(), it may leave 1370 bytes_in_buffer set to 0 (in which case a fill_input_buffer() call 1371 will occur immediately). 1372 1373fill_input_buffer (j_decompress_ptr cinfo) 1374 This is called whenever bytes_in_buffer has reached zero and more 1375 data is wanted. In typical applications, it should read fresh data 1376 into the buffer (ignoring the current state of next_input_byte and 1377 bytes_in_buffer), reset the pointer & count to the start of the 1378 buffer, and return TRUE indicating that the buffer has been reloaded. 1379 It is not necessary to fill the buffer entirely, only to obtain at 1380 least one more byte. bytes_in_buffer MUST be set to a positive value 1381 if TRUE is returned. A FALSE return should only be used when I/O 1382 suspension is desired (this mode is discussed in the next section). 1383 1384skip_input_data (j_decompress_ptr cinfo, long num_bytes) 1385 Skip num_bytes worth of data. The buffer pointer and count should 1386 be advanced over num_bytes input bytes, refilling the buffer as 1387 needed. This is used to skip over a potentially large amount of 1388 uninteresting data (such as an APPn marker). In some applications 1389 it may be possible to optimize away the reading of the skipped data, 1390 but it's not clear that being smart is worth much trouble; large 1391 skips are uncommon. bytes_in_buffer may be zero on return. 1392 A zero or negative skip count should be treated as a no-op. 1393 1394resync_to_restart (j_decompress_ptr cinfo) 1395 This routine is called only when the decompressor has failed to find 1396 a restart (RSTn) marker where one is expected. Its mission is to 1397 find a suitable point for resuming decompression. For most 1398 applications, we recommend that you just use the default resync 1399 procedure, jpeg_resync_to_restart(). However, if you are able to back 1400 up in the input data stream, or if you have a-priori knowledge about 1401 the likely location of restart markers, you may be able to do better. 1402 Read the read_restart_marker() and jpeg_resync_to_restart() routines 1403 in jdmarker.c if you think you'd like to implement your own resync 1404 procedure. 1405 1406term_source (j_decompress_ptr cinfo) 1407 Terminate source --- called by jpeg_finish_decompress() after all 1408 data has been read. Often a no-op. 1409 1410For both fill_input_buffer() and skip_input_data(), there is no such thing 1411as an EOF return. If the end of the file has been reached, the routine has 1412a choice of exiting via ERREXIT() or inserting fake data into the buffer. 1413In most cases, generating a warning message and inserting a fake EOI marker 1414is the best course of action --- this will allow the decompressor to output 1415however much of the image is there. In pathological cases, the decompressor 1416may swallow the EOI and again demand data ... just keep feeding it fake EOIs. 1417jdatasrc.c illustrates the recommended error recovery behavior. 1418 1419term_source() is NOT called by jpeg_abort() or jpeg_destroy(). If you want 1420the source manager to be cleaned up during an abort, you must do it yourself. 1421 1422You will also need code to create a jpeg_source_mgr struct, fill in its method 1423pointers, and insert a pointer to the struct into the "src" field of the JPEG 1424decompression object. This can be done in-line in your setup code if you 1425like, but it's probably cleaner to provide a separate routine similar to the 1426jpeg_stdio_src() routine of the supplied source manager. 1427 1428For more information, consult the stdio source and destination managers 1429in jdatasrc.c and jdatadst.c. 1430 1431 1432I/O suspension 1433-------------- 1434 1435Some applications need to use the JPEG library as an incremental memory-to- 1436memory filter: when the compressed data buffer is filled or emptied, they want 1437control to return to the outer loop, rather than expecting that the buffer can 1438be flushed or reloaded within the data source/destination manager subroutine. 1439The library supports this need by providing an "I/O suspension" mode, which we 1440describe in this section. 1441 1442The I/O suspension mode is a limited solution: it works only in the simplest 1443operating modes (namely single-pass processing of single-scan JPEG files), and 1444it has several other restrictions which are documented below. Furthermore, 1445nothing is guaranteed about the maximum amount of time spent in any one call 1446to the library, so a single-threaded application may still have response-time 1447problems. If you need multi-pass processing or guaranteed response time, we 1448suggest you "bite the bullet" and implement a real multi-tasking capability. 1449 1450To use I/O suspension, cooperation is needed between the calling application 1451and the data source or destination manager; you will always need a custom 1452source/destination manager. (Please read the previous section if you haven't 1453already.) The basic idea is that the empty_output_buffer() or 1454fill_input_buffer() routine is a no-op, merely returning FALSE to indicate 1455that it has done nothing. Upon seeing this, the JPEG library suspends 1456operation and returns to its caller. The surrounding application is 1457responsible for emptying or refilling the work buffer before calling the JPEG 1458library again. 1459 1460Compression suspension: 1461 1462For compression suspension, use an empty_output_buffer() routine that 1463returns FALSE; typically it will not do anything else. This will cause the 1464compressor to return to the caller of jpeg_write_scanlines(), with the 1465return value indicating that not all the supplied scanlines have been 1466accepted. The application must make more room in the output buffer, adjust 1467the buffer pointer/count appropriately, and then call jpeg_write_scanlines() 1468again, pointing to the first unconsumed scanline. 1469 1470When forced to suspend, the compressor will backtrack to a convenient stopping 1471point (usually the start of the current MCU); it will regenerate some output 1472data when restarted. Therefore, although empty_output_buffer() is only called 1473when the buffer is filled, you should NOT dump out the entire buffer, only the 1474data up to the current position of next_output_byte/free_in_buffer. The data 1475beyond that point will be regenerated after resumption. 1476 1477Because of the backtracking behavior, a good-size output buffer is essential 1478for efficiency; you don't want the compressor to suspend often. (In fact, an 1479overly small buffer could lead to infinite looping, if a single MCU required 1480more data than would fit in the buffer.) We recommend a buffer of at least 1481several Kbytes. You may want to insert explicit code to ensure that you don't 1482call jpeg_write_scanlines() unless there is a reasonable amount of space in 1483the output buffer; in other words, flush the buffer before trying to compress 1484more data. 1485 1486The JPEG compressor does not support suspension while it is trying to write 1487JPEG markers at the beginning and end of the file. This means that 1488 * At the beginning of a compression operation, there must be enough free 1489 space in the output buffer to hold the header markers (typically 600 or 1490 so bytes). The recommended buffer size is bigger than this anyway, so 1491 this is not a problem as long as you start with an empty buffer. However, 1492 this restriction might catch you if you insert large special markers, such 1493 as a JFIF thumbnail image. 1494 * When you call jpeg_finish_compress(), there must be enough space in the 1495 output buffer to emit any buffered data and the final EOI marker. In the 1496 current implementation, half a dozen bytes should suffice for this, but 1497 for safety's sake we recommend ensuring that at least 100 bytes are free 1498 before calling jpeg_finish_compress(). 1499Furthermore, since jpeg_finish_compress() cannot suspend, you cannot request 1500multi-pass operating modes such as Huffman code optimization or multiple-scan 1501output. That would imply that a large amount of data would be written inside 1502jpeg_finish_compress(), which would certainly trigger a buffer overrun. 1503 1504Decompression suspension: 1505 1506For decompression suspension, use a fill_input_buffer() routine that simply 1507returns FALSE (except perhaps during error recovery, as discussed below). 1508This will cause the decompressor to return to its caller with an indication 1509that suspension has occurred. This can happen at three places: 1510 * jpeg_read_header(): will return JPEG_SUSPENDED. 1511 * jpeg_read_scanlines(): will return the number of scanlines already 1512 completed (possibly 0). 1513 * jpeg_finish_decompress(): will return FALSE, rather than its usual TRUE. 1514The surrounding application must recognize these cases, load more data into 1515the input buffer, and repeat the call. In the case of jpeg_read_scanlines(), 1516adjust the passed pointers to reflect any scanlines successfully read. 1517 1518Just as with compression, the decompressor will typically backtrack to a 1519convenient restart point before suspending. The data beyond the current 1520position of next_input_byte/bytes_in_buffer must NOT be discarded; it will 1521be re-read upon resumption. In most implementations, you'll need to shift 1522this data down to the start of your work buffer and then load more data 1523after it. Again, this behavior means that a several-Kbyte work buffer is 1524essential for decent performance; furthermore, you should load a reasonable 1525amount of new data before resuming decompression. (If you loaded, say, 1526only one new byte each time around, you could waste a LOT of cycles.) 1527 1528The skip_input_data() source manager routine requires special care in a 1529suspension scenario. This routine is NOT granted the ability to suspend the 1530decompressor; it can decrement bytes_in_buffer to zero, but no more. If the 1531requested skip distance exceeds the amount of data currently in the input 1532buffer, then skip_input_data() must set bytes_in_buffer to zero and record the 1533additional skip distance somewhere else. The decompressor will immediately 1534call fill_input_buffer(), which will return FALSE, which will cause a 1535suspension return. The surrounding application must then arrange to discard 1536the right number of bytes before it resumes loading the input buffer. (Yes, 1537this design is rather baroque, but it avoids complexity in the far more common 1538case where a non-suspending source manager is used.) 1539 1540If the input data has been exhausted, we recommend that you emit a warning 1541and insert dummy EOI markers just as a non-suspending data source manager 1542would do. This can be handled either in the surrounding application logic or 1543within fill_input_buffer(); the latter is probably more efficient. If 1544fill_input_buffer() knows that no more data is available, it can set the 1545pointer/count to point to a dummy EOI marker and then return TRUE just as 1546though it had read more data in a non-suspending situation. 1547 1548The decompressor does not support suspension within jpeg_start_decompress(). 1549This means that you cannot use suspension with any multi-pass processing mode 1550(eg, two-pass color quantization or multiple-scan JPEG files). In single-pass 1551modes, jpeg_start_decompress() reads no data and thus need never suspend. 1552 1553The decompressor does not attempt to suspend within any JPEG marker; it will 1554backtrack to the start of the marker. Hence the input buffer must be large 1555enough to hold the longest marker in the file. We recommend at least a 2K 1556buffer. The buffer would need to be 64K to allow for arbitrary COM or APPn 1557markers, but the decompressor does not actually try to read these; it just 1558skips them by calling skip_input_data(). If you provide a special marker 1559handling routine that does look at such markers, coping with buffer overflow 1560is your problem. Ordinary JPEG markers should normally not exceed a few 1561hundred bytes each (DHT tables are typically the longest). For robustness 1562against damaged marker length counts, you may wish to insert a test in your 1563application for the case that the input buffer is completely full and yet the 1564decoder has suspended without consuming any data --- otherwise, if this 1565situation did occur, it would lead to an endless loop. 1566 1567Multiple-buffer management: 1568 1569In some applications it is desirable to store the compressed data in a linked 1570list of buffer areas, so as to avoid data copying. This can be handled by 1571having empty_output_buffer() or fill_input_buffer() set the pointer and count 1572to reference the next available buffer; FALSE is returned only if no more 1573buffers are available. Although seemingly straightforward, there is a 1574pitfall in this approach: the backtrack that occurs when FALSE is returned 1575could back up into an earlier buffer. Do not discard "completed" buffers in 1576the empty_output_buffer() or fill_input_buffer() routine, unless you can tell 1577from the saved pointer/bytecount that the JPEG library will no longer attempt 1578to backtrack that far. It's probably simplest to postpone releasing any 1579buffers until the library returns to its caller; then you can use the final 1580bytecount to tell how much data has been fully processed, and release buffers 1581on that basis. 1582 1583 1584Abbreviated datastreams and multiple images 1585------------------------------------------- 1586 1587A JPEG compression or decompression object can be reused to process multiple 1588images. This saves a small amount of time per image by eliminating the 1589"create" and "destroy" operations, but that isn't the real purpose of the 1590feature. Rather, reuse of an object provides support for abbreviated JPEG 1591datastreams. Object reuse can also simplify processing a series of images in 1592a single input or output file. This section explains these features. 1593 1594A JPEG file normally contains several hundred bytes worth of quantization 1595and Huffman tables. In a situation where many images will be stored or 1596transmitted with identical tables, this may represent an annoying overhead. 1597The JPEG standard therefore permits tables to be omitted. The standard 1598defines three classes of JPEG datastreams: 1599 * "Interchange" datastreams contain an image and all tables needed to decode 1600 the image. These are the usual kind of JPEG file. 1601 * "Abbreviated image" datastreams contain an image, but are missing some or 1602 all of the tables needed to decode that image. 1603 * "Abbreviated table specification" (henceforth "tables-only") datastreams 1604 contain only table specifications. 1605To decode an abbreviated image, it is necessary to load the missing table(s) 1606into the decoder beforehand. This can be accomplished by reading a separate 1607tables-only file. A variant scheme uses a series of images in which the first 1608image is an interchange (complete) datastream, while subsequent ones are 1609abbreviated and rely on the tables loaded by the first image. It is assumed 1610that once the decoder has read a table, it will remember that table until a 1611new definition for the same table number is encountered. 1612 1613It is the application designer's responsibility to figure out how to associate 1614the correct tables with an abbreviated image. While abbreviated datastreams 1615can be useful in a closed environment, their use is strongly discouraged in 1616any situation where data exchange with other applications might be needed. 1617Caveat designer. 1618 1619The JPEG library provides support for reading and writing any combination of 1620tables-only datastreams and abbreviated images. In both compression and 1621decompression objects, a quantization or Huffman table will be retained for 1622the lifetime of the object, unless it is overwritten by a new table definition. 1623 1624 1625To create abbreviated image datastreams, it is only necessary to tell the 1626compressor not to emit some or all of the tables it is using. Each 1627quantization and Huffman table struct contains a boolean field "sent_table", 1628which normally is initialized to FALSE. For each table used by the image, the 1629header-writing process emits the table and sets sent_table = TRUE unless it is 1630already TRUE. (In normal usage, this prevents outputting the same table 1631definition multiple times, as would otherwise occur because the chroma 1632components typically share tables.) Thus, setting this field to TRUE before 1633calling jpeg_start_compress() will prevent the table from being written at 1634all. 1635 1636If you want to create a "pure" abbreviated image file containing no tables, 1637just call "jpeg_suppress_tables(&cinfo, TRUE)" after constructing all the 1638tables. If you want to emit some but not all tables, you'll need to set the 1639individual sent_table fields directly. 1640 1641To create an abbreviated image, you must also call jpeg_start_compress() 1642with a second parameter of FALSE, not TRUE. Otherwise jpeg_start_compress() 1643will force all the sent_table fields to FALSE. (This is a safety feature to 1644prevent abbreviated images from being created accidentally.) 1645 1646To create a tables-only file, perform the same parameter setup that you 1647normally would, but instead of calling jpeg_start_compress() and so on, call 1648jpeg_write_tables(&cinfo). This will write an abbreviated datastream 1649containing only SOI, DQT and/or DHT markers, and EOI. All the quantization 1650and Huffman tables that are currently defined in the compression object will 1651be emitted unless their sent_tables flag is already TRUE, and then all the 1652sent_tables flags will be set TRUE. 1653 1654A sure-fire way to create matching tables-only and abbreviated image files 1655is to proceed as follows: 1656 1657 create JPEG compression object 1658 set JPEG parameters 1659 set destination to tables-only file 1660 jpeg_write_tables(&cinfo); 1661 set destination to image file 1662 jpeg_start_compress(&cinfo, FALSE); 1663 write data... 1664 jpeg_finish_compress(&cinfo); 1665 1666Since the JPEG parameters are not altered between writing the table file and 1667the abbreviated image file, the same tables are sure to be used. Of course, 1668you can repeat the jpeg_start_compress() ... jpeg_finish_compress() sequence 1669many times to produce many abbreviated image files matching the table file. 1670 1671You cannot suppress output of the computed Huffman tables when Huffman 1672optimization is selected. (If you could, there'd be no way to decode the 1673image...) Generally, you don't want to set optimize_coding = TRUE when 1674you are trying to produce abbreviated files. 1675 1676In some cases you might want to compress an image using tables which are 1677not stored in the application, but are defined in an interchange or 1678tables-only file readable by the application. This can be done by setting up 1679a JPEG decompression object to read the specification file, then copying the 1680tables into your compression object. 1681 1682 1683To read abbreviated image files, you simply need to load the proper tables 1684into the decompression object before trying to read the abbreviated image. 1685If the proper tables are stored in the application program, you can just 1686allocate the table structs and fill in their contents directly. More commonly 1687you'd want to read the tables from a tables-only file. The jpeg_read_header() 1688call is sufficient to read a tables-only file. You must pass a second 1689parameter of FALSE to indicate that you do not require an image to be present. 1690Thus, the typical scenario is 1691 1692 create JPEG decompression object 1693 set source to tables-only file 1694 jpeg_read_header(&cinfo, FALSE); 1695 set source to abbreviated image file 1696 jpeg_read_header(&cinfo, TRUE); 1697 set decompression parameters 1698 jpeg_start_decompress(&cinfo); 1699 read data... 1700 jpeg_finish_decompress(&cinfo); 1701 1702In some cases, you may want to read a file without knowing whether it contains 1703an image or just tables. In that case, pass FALSE and check the return value 1704from jpeg_read_header(): it will be JPEG_HEADER_OK if an image was found, 1705JPEG_HEADER_TABLES_ONLY if only tables were found. (A third return value, 1706JPEG_SUSPENDED, is possible when using a suspending data source manager.) 1707Note that jpeg_read_header() will not complain if you read an abbreviated 1708image for which you haven't loaded the missing tables; the missing-table check 1709occurs in jpeg_start_decompress(). 1710 1711 1712It is possible to read a series of images from a single source file by 1713repeating the jpeg_read_header() ... jpeg_finish_decompress() sequence, 1714without releasing/recreating the JPEG object or the data source module. 1715(If you did reinitialize, any partial bufferload left in the data source 1716buffer at the end of one image would be discarded, causing you to lose the 1717start of the next image.) When you use this method, stored tables are 1718automatically carried forward, so some of the images can be abbreviated images 1719that depend on tables from earlier images. 1720 1721If you intend to write a series of images into a single destination file, 1722you might want to make a specialized data destination module that doesn't 1723flush the output buffer at term_destination() time. This would speed things 1724up by some trifling amount. Of course, you'd need to remember to flush the 1725buffer after the last image. You can make the later images be abbreviated 1726ones by passing FALSE to jpeg_start_compress(). 1727 1728 1729Special markers 1730--------------- 1731 1732Some applications may need to insert or extract special data in the JPEG 1733datastream. The JPEG standard provides marker types "COM" (comment) and 1734"APP0" through "APP15" (application) to hold application-specific data. 1735Unfortunately, the use of these markers is not specified by the standard. 1736COM markers are fairly widely used to hold user-supplied text. The JFIF file 1737format spec uses APP0 markers with specified initial strings to hold certain 1738data. Adobe applications use APP14 markers beginning with the string "Adobe" 1739for miscellaneous data. Other APPn markers are rarely seen, but might 1740contain almost anything. 1741 1742If you wish to store user-supplied text, we recommend you use COM markers 1743and place readable 7-bit ASCII text in them. Newline conventions are not 1744standardized --- expect to find LF (Unix style), CR/LF (DOS style), or CR 1745(Mac style). A robust COM reader should be able to cope with random binary 1746garbage, including nulls, since some applications generate COM markers 1747containing non-ASCII junk. (But yours should not be one of them.) 1748 1749For program-supplied data, use an APPn marker, and be sure to begin it with an 1750identifying string so that you can tell whether the marker is actually yours. 1751It's probably best to avoid using APP0 or APP14 for any private markers. 1752 1753Keep in mind that at most 65533 bytes can be put into one marker, but you 1754can have as many markers as you like. 1755 1756By default, the JPEG compression library will write a JFIF APP0 marker if the 1757selected JPEG colorspace is grayscale or YCbCr, or an Adobe APP14 marker if 1758the selected colorspace is RGB, CMYK, or YCCK. You can disable this, but 1759we don't recommend it. The decompression library will recognize JFIF and 1760Adobe markers and will set the JPEG colorspace properly when one is found. 1761 1762You can write special markers immediately following the datastream header by 1763calling jpeg_write_marker() after jpeg_start_compress() and before the first 1764call to jpeg_write_scanlines(). When you do this, the markers appear after 1765the SOI and the JFIF APP0 and Adobe APP14 markers (if written), but before 1766all else. Write the marker type parameter as "JPEG_COM" for COM or 1767"JPEG_APP0 + n" for APPn. (Actually, jpeg_write_marker will let you write 1768any marker type, but we don't recommend writing any other kinds of marker.) 1769For example, to write a user comment string pointed to by comment_text: 1770 jpeg_write_marker(cinfo, JPEG_COM, comment_text, strlen(comment_text)); 1771Or if you prefer to synthesize the marker byte sequence yourself, you can 1772just cram it straight into the data destination module. 1773 1774For decompression, you can supply your own routine to process COM or APPn 1775markers by calling jpeg_set_marker_processor(). Usually you'd call this 1776after creating a decompression object and before calling jpeg_read_header(), 1777because the markers of interest will normally be scanned by jpeg_read_header. 1778Once you've supplied a routine, it will be used for the life of that 1779decompression object. A separate routine may be registered for COM and for 1780each APPn marker code. 1781 1782A marker processor routine must have the signature 1783 boolean jpeg_marker_parser_method (j_decompress_ptr cinfo) 1784Although the marker code is not explicitly passed, the routine can find it 1785in cinfo->unread_marker. At the time of call, the marker proper has been 1786read from the data source module. The processor routine is responsible for 1787reading the marker length word and the remaining parameter bytes, if any. 1788Return TRUE to indicate success. (FALSE should be returned only if you are 1789using a suspending data source and it tells you to suspend. See the standard 1790marker processors in jdmarker.c for appropriate coding methods if you need to 1791use a suspending data source.) 1792 1793If you override the default APP0 or APP14 processors, it is up to you to 1794recognize JFIF and Adobe markers if you want colorspace recognition to occur 1795properly. We recommend copying and extending the default processors if you 1796want to do that. 1797 1798A simple example of an external COM processor can be found in djpeg.c. 1799 1800 1801Raw (downsampled) image data 1802---------------------------- 1803 1804Some applications need to supply already-downsampled image data to the JPEG 1805compressor, or to receive raw downsampled data from the decompressor. The 1806library supports this requirement by allowing the application to write or 1807read raw data, bypassing the normal preprocessing or postprocessing steps. 1808The interface is different from the standard one and is somewhat harder to 1809use. If your interest is merely in bypassing color conversion, we recommend 1810that you use the standard interface and simply set jpeg_color_space = 1811in_color_space (or jpeg_color_space = out_color_space for decompression). 1812The mechanism described in this section is necessary only to supply or 1813receive downsampled image data, in which not all components have the same 1814dimensions. 1815 1816 1817To compress raw data, you must supply the data in the colorspace to be used 1818in the JPEG file (please read the earlier section on Special color spaces) 1819and downsampled to the sampling factors specified in the JPEG parameters. 1820You must supply the data in the format used internally by the JPEG library, 1821namely a JSAMPIMAGE array. This is an array of pointers to two-dimensional 1822arrays, each of type JSAMPARRAY. Each 2-D array holds the values for one 1823color component. This structure is necessary since the components are of 1824different sizes. If the image dimensions are not a multiple of the MCU size, 1825you must also pad the data correctly (usually, this is done by replicating 1826the last column and/or row). The data must be padded to a multiple of a DCT 1827block in each component: that is, each downsampled row must contain a 1828multiple of 8 valid samples, and there must be a multiple of 8 sample rows 1829for each component. (For applications such as conversion of digital TV 1830images, the standard image size is usually a multiple of the DCT block size, 1831so that no padding need actually be done.) 1832 1833The procedure for compression of raw data is basically the same as normal 1834compression, except that you call jpeg_write_raw_data() in place of 1835jpeg_write_scanlines(). Before calling jpeg_start_compress(), you must do 1836the following: 1837 * Set cinfo->raw_data_in to TRUE. (It is set FALSE by jpeg_set_defaults().) 1838 This notifies the library that you will be supplying raw data. 1839 * Ensure jpeg_color_space is correct --- an explicit jpeg_set_colorspace() 1840 call is a good idea. Note that since color conversion is bypassed, 1841 in_color_space is ignored, except that jpeg_set_defaults() uses it to 1842 choose the default jpeg_color_space setting. 1843 * Ensure the sampling factors, cinfo->comp_info[i].h_samp_factor and 1844 cinfo->comp_info[i].v_samp_factor, are correct. Since these indicate the 1845 dimensions of the data you are supplying, it's wise to set them 1846 explicitly, rather than assuming the library's defaults are what you want. 1847 1848To pass raw data to the library, call jpeg_write_raw_data() in place of 1849jpeg_write_scanlines(). The two routines work similarly except that 1850jpeg_write_raw_data takes a JSAMPIMAGE data array rather than JSAMPARRAY. 1851The scanlines count passed to and returned from jpeg_write_raw_data is 1852measured in terms of the component with the largest v_samp_factor. 1853 1854jpeg_write_raw_data() processes one MCU row per call, which is to say 1855v_samp_factor*DCTSIZE sample rows of each component. The passed num_lines 1856value must be at least max_v_samp_factor*DCTSIZE, and the return value will 1857be exactly that amount (or possibly some multiple of that amount, in future 1858library versions). This is true even on the last call at the bottom of the 1859image; don't forget to pad your data as necessary. 1860 1861The required dimensions of the supplied data can be computed for each 1862component as 1863 cinfo->comp_info[i].width_in_blocks*DCTSIZE samples per row 1864 cinfo->comp_info[i].height_in_blocks*DCTSIZE rows in image 1865after jpeg_start_compress() has initialized those fields. If the valid data 1866is smaller than this, it must be padded appropriately. For some sampling 1867factors and image sizes, additional dummy DCT blocks are inserted to make 1868the image a multiple of the MCU dimensions. The library creates such dummy 1869blocks itself; it does not read them from your supplied data. Therefore you 1870need never pad by more than DCTSIZE samples. An example may help here. 1871Assume 2h2v downsampling of YCbCr data, that is 1872 cinfo->comp_info[0].h_samp_factor = 2 for Y 1873 cinfo->comp_info[0].v_samp_factor = 2 1874 cinfo->comp_info[1].h_samp_factor = 1 for Cb 1875 cinfo->comp_info[1].v_samp_factor = 1 1876 cinfo->comp_info[2].h_samp_factor = 1 for Cr 1877 cinfo->comp_info[2].v_samp_factor = 1 1878and suppose that the nominal image dimensions (cinfo->image_width and 1879cinfo->image_height) are 101x101 pixels. Then jpeg_start_compress() will 1880compute downsampled_width = 101 and width_in_blocks = 13 for Y, 1881downsampled_width = 51 and width_in_blocks = 7 for Cb and Cr (and the same 1882for the height fields). You must pad the Y data to at least 13*8 = 104 1883columns and rows, the Cb/Cr data to at least 7*8 = 56 columns and rows. The 1884MCU height is max_v_samp_factor = 2 DCT rows so you must pass at least 16 1885scanlines on each call to jpeg_write_raw_data(), which is to say 16 actual 1886sample rows of Y and 8 each of Cb and Cr. A total of 7 MCU rows are needed, 1887so you must pass a total of 7*16 = 112 "scanlines". The last DCT block row 1888of Y data is dummy, so it doesn't matter what you pass for it in the data 1889arrays, but the scanlines count must total up to 112 so that all of the Cb 1890and Cr data gets passed. 1891 1892Currently, output suspension is not supported with raw data output: an error 1893will result if the data destination module tries to suspend. 1894 1895 1896Decompression with raw data output implies bypassing all postprocessing: 1897you cannot ask for color quantization, for instance. More seriously, you must 1898deal with the color space and sampling factors present in the incoming file. 1899If your application only handles, say, 2h1v YCbCr data, you must check for 1900and fail on other color spaces or other sampling factors. 1901 1902To obtain raw data output, set cinfo->raw_data_out = TRUE before 1903jpeg_start_decompress() (it is set FALSE by jpeg_read_header()). Be sure to 1904verify that the color space and sampling factors are ones you can handle. 1905Then call jpeg_read_raw_data() in place of jpeg_read_scanlines(). The 1906decompression process is otherwise the same as usual. 1907 1908jpeg_read_raw_data() returns one MCU row per call, and thus you must pass a 1909buffer of at least max_v_samp_factor*DCTSIZE scanlines (scanline counting is 1910the same as for raw-data compression). The buffer you pass must be large 1911enough to hold the actual data plus padding to DCT-block boundaries. As with 1912compression, any entirely dummy DCT blocks are not processed so you need not 1913allocate space for them, but the total scanline count includes them. The 1914above example of computing buffer dimensions for raw-data compression is 1915equally valid for decompression. 1916 1917Input suspension is supported with raw-data decompression: if the data source 1918module suspends, jpeg_read_raw_data() will return 0. 1919 1920 1921Progress monitoring 1922------------------- 1923 1924Some applications may need to regain control from the JPEG library every so 1925often. The typical use of this feature is to produce a percent-done bar or 1926other progress display. (For a simple example, see cjpeg.c or djpeg.c.) 1927Although you do get control back frequently during the data-transferring pass 1928(the jpeg_read_scanlines or jpeg_write_scanlines loop), any additional passes 1929will occur inside jpeg_finish_compress or jpeg_start_decompress; those 1930routines may take a long time to execute, and you don't get control back 1931until they are done. 1932 1933You can define a progress-monitor routine which will be called periodically 1934by the library. No guarantees are made about how often this call will occur, 1935so we don't recommend you use it for mouse tracking or anything like that. 1936At present, a call will occur once per MCU row, scanline, or sample row 1937group, whichever unit is convenient for the current processing mode; so the 1938wider the image, the longer the time between calls. (During the data 1939transferring pass, only one call occurs per call of jpeg_read_scanlines or 1940jpeg_write_scanlines, so don't pass a large number of scanlines at once if 1941you want fine resolution in the progress count.) 1942 1943To establish a progress-monitor callback, create a struct jpeg_progress_mgr, 1944fill in its progress_monitor field with a pointer to your callback routine, 1945and set cinfo->progress to point to the struct. The callback will be called 1946whenever cinfo->progress is non-NULL. (This pointer is set to NULL by 1947jpeg_create_compress or jpeg_create_decompress; the library will not change 1948it thereafter. So if you allocate dynamic storage for the progress struct, 1949make sure it will live as long as the JPEG object does. Allocating from the 1950JPEG memory manager with lifetime JPOOL_PERMANENT will work nicely.) You 1951can use the same callback routine for both compression and decompression. 1952 1953The jpeg_progress_mgr struct contains four fields which are set by the library: 1954 long pass_counter; /* work units completed in this pass */ 1955 long pass_limit; /* total number of work units in this pass */ 1956 int completed_passes; /* passes completed so far */ 1957 int total_passes; /* total number of passes expected */ 1958During any one pass, pass_counter increases from 0 up to (not including) 1959pass_limit; the step size is not necessarily 1. Both the step size and the 1960limit may differ from one pass to another. The expected total number of 1961passes is in total_passes, and the number of passes already completed is in 1962completed_passes. Thus the fraction of work completed may be estimated as 1963 completed_passes + (pass_counter/pass_limit) 1964 -------------------------------------------- 1965 total_passes 1966ignoring the fact that the passes may not be equal amounts of work. 1967 1968When decompressing, the total_passes value is not trustworthy, because it 1969depends on the number of scans in the JPEG file, which isn't always known in 1970advance. In the current implementation, completed_passes may jump by more 1971than one when dealing with a multiple-scan input file. About all that is 1972really safe to assume is that when completed_passes = total_passes - 1, the 1973current pass will be the last one. 1974 1975If you really need to use the callback mechanism for time-critical tasks 1976like mouse tracking, you could insert additional calls inside some of the 1977library's inner loops. 1978 1979 1980Memory management 1981----------------- 1982 1983This section covers some key facts about the JPEG library's built-in memory 1984manager. For more info, please read structure.doc's section about the memory 1985manager, and consult the source code if necessary. 1986 1987All memory and temporary file allocation within the library is done via the 1988memory manager. If necessary, you can replace the "back end" of the memory 1989manager to control allocation yourself (for example, if you don't want the 1990library to use malloc() and free() for some reason). 1991 1992Some data is allocated "permanently" and will not be freed until the JPEG 1993object is destroyed. Most data is allocated "per image" and is freed by 1994jpeg_finish_compress, jpeg_finish_decompress, or jpeg_abort. You can call the 1995memory manager yourself to allocate structures that will automatically be 1996freed at these times. Typical code for this is 1997 ptr = (*cinfo->mem->alloc_small) ((j_common_ptr) cinfo, JPOOL_IMAGE, size); 1998Use JPOOL_PERMANENT to get storage that lasts as long as the JPEG object. 1999Use alloc_large instead of alloc_small for anything bigger than a few Kbytes. 2000There are also alloc_sarray and alloc_barray routines that automatically 2001build 2-D sample or block arrays. 2002 2003The library's minimum space requirements to process an image depend on the 2004image's width, but not on its height, because the library ordinarily works 2005with "strip" buffers that are as wide as the image but just a few rows high. 2006Some operating modes (eg, two-pass color quantization) require full-image 2007buffers. Such buffers are treated as "virtual arrays": only the current strip 2008need be in memory, and the rest can be swapped out to a temporary file. 2009 2010If you use the simplest memory manager back end (jmemnobs.c), then no 2011temporary files are used; virtual arrays are simply malloc()'d. Images bigger 2012than memory can be processed only if your system supports virtual memory. 2013The other memory manager back ends support temporary files of various flavors 2014and thus work in machines without virtual memory. They may also be useful on 2015Unix machines if you need to process images that exceed available swap space. 2016 2017When using temporary files, the library will make the in-memory buffers for 2018its virtual arrays just big enough to stay within a "maximum memory" setting. 2019Your application can set this limit by setting cinfo->mem->max_memory_to_use 2020after creating the JPEG object. (Of course, there is still a minimum size for 2021the buffers, so the max-memory setting is effective only if it is bigger than 2022the minimum space needed.) If you allocate any large structures yourself, you 2023must allocate them before jpeg_start_compress() or jpeg_start_decompress() in 2024order to have them counted against the max memory limit. Also keep in mind 2025that space allocated with alloc_small() is ignored, on the assumption that 2026it's too small to be worth worrying about. 2027 2028If you use the jmemname.c or jmemdos.c memory manager back end, it is 2029important to clean up the JPEG object properly to ensure that the temporary 2030files get deleted. (This is especially crucial with jmemdos.c, where the 2031"temporary files" may be extended-memory segments; if they are not freed, 2032DOS will require a reboot to recover the memory.) Thus, with these memory 2033managers, it's a good idea to provide a signal handler that will trap any 2034early exit from your program. The handler should call either jpeg_abort() 2035or jpeg_destroy() for any active JPEG objects. A handler is not needed with 2036jmemnobs.c, and shouldn't be necessary with jmemansi.c either, since the C 2037library is supposed to take care of deleting files made with tmpfile(). 2038 2039 2040Library compile-time options 2041---------------------------- 2042 2043A number of compile-time options are available by modifying jmorecfg.h. 2044 2045The JPEG standard provides for both the baseline 8-bit DCT process and 2046a 12-bit DCT process. 12-bit lossy JPEG is supported if you define 2047BITS_IN_JSAMPLE as 12 rather than 8. Note that this causes JSAMPLE to be 2048larger than a char, so it affects the surrounding application's image data. 2049The sample applications cjpeg and djpeg can support 12-bit mode only for PPM 2050and GIF file formats; you must disable the other file formats to compile a 205112-bit cjpeg or djpeg. At present, a 12-bit library can handle *only* 205212-bit images, not both precisions. (If you need to include both 8- and 205312-bit libraries in a single application, you could probably do it by 2054defining NEED_SHORT_EXTERNAL_NAMES for just one of the copies. You'd have 2055to access the 8-bit and 12-bit copies from separate application source 2056files. This is untested ... if you try it, we'd like to hear whether it 2057works!) 2058 2059The maximum number of components (color channels) in the image is determined 2060by MAX_COMPONENTS. The JPEG standard allows up to 255 components, but we 2061expect that few applications will need more than four or so. 2062 2063On machines with unusual data type sizes, you may be able to improve 2064performance or reduce memory space by tweaking the various typedefs in 2065jmorecfg.h. In particular, on some RISC CPUs, access to arrays of "short"s 2066is quite slow; consider trading memory for speed by making JCOEF, INT16, and 2067UINT16 be "int" or "unsigned int". UINT8 is also a candidate to become int. 2068You probably don't want to make JSAMPLE be int unless you have lots of memory 2069to burn. 2070 2071You can reduce the size of the library by compiling out various optional 2072functions. To do this, undefine xxx_SUPPORTED symbols as necessary. 2073 2074 2075Portability considerations 2076-------------------------- 2077 2078The JPEG library has been written to be extremely portable; the sample 2079applications cjpeg and djpeg are slightly less so. This section summarizes 2080the design goals in this area. (If you encounter any bugs that cause the 2081library to be less portable than is claimed here, we'd appreciate hearing 2082about them.) 2083 2084The code works fine on both ANSI and pre-ANSI C compilers, using any of the 2085popular system include file setups, and some not-so-popular ones too. See 2086install.doc for configuration procedures. 2087 2088The code is not dependent on the exact sizes of the C data types. As 2089distributed, we make the assumptions that 2090 char is at least 8 bits wide 2091 short is at least 16 bits wide 2092 int is at least 16 bits wide 2093 long is at least 32 bits wide 2094(These are the minimum requirements of the ANSI C standard.) Wider types will 2095work fine, although memory may be used inefficiently if char is much larger 2096than 8 bits or short is much bigger than 16 bits. The code should work 2097equally well with 16- or 32-bit ints. 2098 2099In a system where these assumptions are not met, you may be able to make the 2100code work by modifying the typedefs in jmorecfg.h. However, you will probably 2101have difficulty if int is less than 16 bits wide, since references to plain 2102int abound in the code. 2103 2104char can be either signed or unsigned, although the code runs faster if an 2105unsigned char type is available. If char is wider than 8 bits, you will need 2106to redefine JOCTET and/or provide custom data source/destination managers so 2107that JOCTET represents exactly 8 bits of data on external storage. 2108 2109The JPEG library proper does not assume ASCII representation of characters. 2110But some of the image file I/O modules in cjpeg/djpeg do have ASCII 2111dependencies in file-header manipulation; so does cjpeg's select_file_type() 2112routine. 2113 2114The JPEG library does not rely heavily on the C library. In particular, C 2115stdio is used only by the data source/destination modules and the error 2116handler, all of which are application-replaceable. (cjpeg/djpeg are more 2117heavily dependent on stdio.) malloc and free are called only from the memory 2118manager "back end" module, so you can use a different memory allocator by 2119replacing that one file. 2120 2121The code generally assumes that C names must be unique in the first 15 2122characters. However, global function names can be made unique in the 2123first 6 characters by defining NEED_SHORT_EXTERNAL_NAMES. 2124 2125More info about porting the code may be gleaned by reading jconfig.doc, 2126jmorecfg.h, and jinclude.h. 2127 2128 2129Notes for MS-DOS implementors 2130----------------------------- 2131 2132The IJG code is designed to work efficiently in 80x86 "small" or "medium" 2133memory models (i.e., data pointers are 16 bits unless explicitly declared 2134"far"; code pointers can be either size). You may be able to use small 2135model to compile cjpeg or djpeg by itself, but you will probably have to use 2136medium model for any larger application. This won't make much difference in 2137performance. You *will* take a noticeable performance hit if you use a 2138large-data memory model (perhaps 10%-25%), and you should avoid "huge" model 2139if at all possible. 2140 2141The JPEG library typically needs 2Kb-3Kb of stack space. It will also 2142malloc about 20K-30K of near heap space while executing (and lots of far 2143heap, but that doesn't count in this calculation). This figure will vary 2144depending on selected operating mode, and to a lesser extent on image size. 2145There is also about 5Kb-6Kb of constant data which will be allocated in the 2146near data segment (about 4Kb of this is the error message table). 2147Thus you have perhaps 20K available for other modules' static data and near 2148heap space before you need to go to a larger memory model. The C library's 2149static data will account for several K of this, but that still leaves a good 2150deal for your needs. (If you are tight on space, you could reduce the sizes 2151of the I/O buffers allocated by jdatasrc.c and jdatadst.c, say from 4K to 21521K.) 2153 2154About 2K of the near heap space is "permanent" memory that will not be 2155released until you destroy the JPEG object. This is only an issue if you 2156save a JPEG object between compression or decompression operations. 2157 2158Far data space may also be a tight resource when you are dealing with large 2159images. The most memory-intensive case is decompression with two-pass color 2160quantization, or single-pass quantization to an externally supplied color 2161map. This requires a 128Kb color lookup table plus strip buffers amounting 2162to about 50 bytes per column for typical sampling ratios (eg, about 32000 2163bytes for a 640-pixel-wide image). You may not be able to process wide 2164images if you have large data structures of your own. 2165 2166Of course, all of these concerns vanish if you use a 32-bit flat-memory-model 2167compiler, such as DJGPP or Watcom C. We highly recommend flat model if you 2168can use it; the JPEG library is significantly faster in flat model. 2169