diff --git a/Image/jpeg/decstation/libjpeg.doc b/Image/jpeg/decstation/libjpeg.doc deleted file mode 100644 index 83067d1..0000000 --- a/Image/jpeg/decstation/libjpeg.doc +++ /dev/null @@ -1,2144 +0,0 @@ -USING THE IJG JPEG LIBRARY - -Copyright (C) 1994, Thomas G. Lane. -This file is part of the Independent JPEG Group's software. -For conditions of distribution and use, see the accompanying README file. - - -This file describes how to use the IJG JPEG library within an application -program. Read it if you want to write a program that uses the library. - -The file example.c provides heavily commented skeleton code for calling the -JPEG library. Also see jpeglib.h (the include file to be used by application -programs) for full details about data structures and function parameter lists. -The library source code, of course, is the ultimate reference. - -Note that there have been *major* changes from the application interface -presented by IJG version 4 and earlier versions. The old design had several -inherent limitations, and it had accumulated a lot of cruft as we added -features while trying to minimize application-interface changes. We have -sacrificed backward compatibility in the version 5 rewrite, but we think the -improvements justify this. - - -TABLE OF CONTENTS ------------------ - -Overview: - Functions provided by the library - Outline of typical usage -Basic library usage: - Data formats - Compression details - Decompression details - Mechanics of usage: include files, linking, etc -Advanced features: - Compression parameter selection - Decompression parameter selection - Special color spaces - Error handling - Compressed data handling (source and destination managers) - I/O suspension - Abbreviated datastreams and multiple images - Special markers - Raw (downsampled) image data - Progress monitoring - Memory management - Library compile-time options - Portability considerations - Notes for MS-DOS implementors - -You should read at least the overview and basic usage sections before trying -to program with the library. The sections on advanced features can be read -if and when you need them. - - -OVERVIEW -======== - -Functions provided by the library ---------------------------------- - -The IJG JPEG library provides C code to read and write JPEG-compressed image -files. The surrounding application program receives or supplies image data a -scanline at a time, using a straightforward uncompressed image format. All -details of color conversion and other preprocessing/postprocessing can be -handled by the library. - -The library includes a substantial amount of code that is not covered by the -JPEG standard but is necessary for typical applications of JPEG. These -functions preprocess the image before JPEG compression or postprocess it after -decompression. They include colorspace conversion, downsampling/upsampling, -and color quantization. The application indirectly selects use of this code -by specifying the format in which it wishes to supply or receive image data. -For example, if colormapped output is requested, then the decompression -library automatically invokes color quantization. - -A wide range of quality vs. speed tradeoffs are possible in JPEG processing, -and even more so in decompression postprocessing. The decompression library -provides multiple implementations that cover most of the useful tradeoffs, -ranging from very-high-quality down to fast-preview operation. On the -compression side we have generally not provided low-quality choices, since -compression is normally less time-critical. It should be understood that the -low-quality modes may not meet the JPEG standard's accuracy requirements; -nonetheless, they are useful for viewers. - -A word about functions *not* provided by the library. We handle a subset of -the ISO JPEG standard; most baseline and extended-sequential JPEG processes -are supported. (Our subset includes all features now in common use.) -Unsupported ISO options include: - * Progressive storage (may be supported in future versions) - * Hierarchical storage - * Lossless JPEG - * Arithmetic entropy coding (unsupported for legal reasons) - * DNL marker - * Nonintegral subsampling ratios -We support both 8- and 12-bit data precision, but this is a compile-time -choice rather than a run-time choice; hence it is difficult to use both -precisions in a single application. - -By itself, the library handles only interchange JPEG datastreams --- in -particular the widely used JFIF file format. The library can be used by -surrounding code to process interchange or abbreviated JPEG datastreams that -are embedded in more complex file formats. (For example, we anticipate that -Sam Leffler's LIBTIFF library will use this code to support the revised TIFF -JPEG format.) - - -Outline of typical usage ------------------------- - -The rough outline of a JPEG compression operation is: - - Allocate and initialize a JPEG compression object - Specify the destination for the compressed data (eg, a file) - Set parameters for compression, including image size & colorspace - jpeg_start_compress(...); - while (scan lines remain to be written) - jpeg_write_scanlines(...); - jpeg_finish_compress(...); - Release the JPEG compression object - -A JPEG compression object holds parameters and working state for the JPEG -library. We make creation/destruction of the object separate from starting -or finishing compression of an image; the same object can be re-used for a -series of image compression operations. This makes it easy to re-use the -same parameter settings for a sequence of images. Re-use of a JPEG object -also has important implications for processing abbreviated JPEG datastreams, -as discussed later. - -The image data to be compressed is supplied to jpeg_write_scanlines() from -in-memory buffers. If the application is doing file-to-file compression, -reading image data from the source file is the application's responsibility. -The library emits compressed data by calling a "data destination manager", -which typically will write the data into a file; but the application can -provide its own destination manager to do something else. - -Similarly, the rough outline of a JPEG decompression operation is: - - Allocate and initialize a JPEG decompression object - Specify the source of the compressed data (eg, a file) - Call jpeg_read_header() to obtain image info - Set parameters for decompression - jpeg_start_decompress(...); - while (scan lines remain to be read) - jpeg_read_scanlines(...); - jpeg_finish_decompress(...); - Release the JPEG decompression object - -This is comparable to the compression outline except that reading the -datastream header is a separate step. This is helpful because information -about the image's size, colorspace, etc is available when the application -selects decompression parameters. For example, the application can choose an -output scaling ratio that will fit the image into the available screen size. - -The decompression library obtains compressed data by calling a data source -manager, which typically will read the data from a file; but other behaviors -can be obtained with a custom source manager. Decompressed data is delivered -into in-memory buffers passed to jpeg_read_scanlines(). - -It is possible to abort an incomplete compression or decompression operation -by calling jpeg_abort(); or, if you do not need to retain the JPEG object, -simply release it by calling jpeg_destroy(). - -JPEG compression and decompression objects are two separate struct types. -However, they share some common fields, and certain routines such as -jpeg_destroy() can work on either type of object. - -The JPEG library has no static variables: all state is in the compression -or decompression object. Therefore it is possible to process multiple -compression and decompression operations concurrently, using multiple JPEG -objects. - -Both compression and decompression can be done in an incremental memory-to- -memory fashion, if suitable source/destination managers are used. However, -there are some restrictions on the processing that can be done in this mode. -See the section on "I/O suspension" for more details. - - -BASIC LIBRARY USAGE -=================== - -Data formats ------------- - -Before diving into procedural details, it is helpful to understand the -image data format that the JPEG library expects or returns. - -The standard input image format is a rectangular array of pixels, with each -pixel having the same number of "component" values (color channels). You -must specify how many components there are and the colorspace interpretation -of the components. Most applications will use RGB data (three components -per pixel) or grayscale data (one component per pixel). - -Note that there is no provision for colormapped input. You can feed in a -colormapped image by expanding it to full-color format. However JPEG often -doesn't work very well with colormapped source data, because of dithering -noise. This is discussed in more detail in the JPEG FAQ and the other -references mentioned in the README file. - -Pixels are stored by scanlines, with each scanline running from left to -right. The component values for each pixel are adjacent in the row; for -example, R,G,B,R,G,B,R,G,B,... for 24-bit RGB color. Each scanline is an -array of data type JSAMPLE --- which is typically "unsigned char", unless -you've changed jmorecfg.h. (You can also change the RGB pixel layout, say -to B,G,R order, by modifying jmorecfg.h. But see the restrictions listed in -that file before doing so.) - -A 2-D array of pixels is formed by making a list of pointers to the starts of -scanlines; so the scanlines need not be physically adjacent in memory. Even -if you process just one scanline at a time, you must make a one-element -pointer array to serve this purpose. Pointers to JSAMPLE rows are of type -JSAMPROW, and the pointer to the pointer array is of type JSAMPARRAY. - -The library accepts or supplies one or more complete scanlines per call. -It is not possible to process part of a row at a time. Scanlines are always -processed top-to-bottom. You can process an entire image in one call if you -have it all in memory, but usually it's simplest to process one scanline at -a time. - -For best results, source data values should have the precision specified by -BITS_IN_JSAMPLE (normally 8 bits). For instance, if you choose to compress -data that's only 6 bits/channel, you should left-justify each value in a -byte before passing it to the compressor. If you need to compress data -that has more than 8 bits/channel, compile with BITS_IN_JSAMPLE = 12. -(See "Library compile-time options", later.) - -The data format returned by the decompressor is the same in all details, -except that colormapped data is supported. If you request colormapped -output then the returned data array contains a single JSAMPLE per pixel; -its value is an index into a color map. The color map is represented as -a 2-D JSAMPARRAY in which each row holds the values of one color component, -that is, colormap[i][j] is the value of the i'th color component for pixel -value (map index) j. Note that since the colormap indexes are stored in -JSAMPLEs, the maximum number of colors is limited by the size of JSAMPLE -(ie, at most 256 colors for an 8-bit JPEG library). - - -Compression details -------------------- - -Here we revisit the JPEG compression outline given in the overview. - -1. Allocate and initialize a JPEG compression object. - -A JPEG compression object is a "struct jpeg_compress_struct" (plus a bunch of -subsidiary structures which are allocated via malloc(), but the application -doesn't control those directly). This struct can be just a local variable in -the calling routine, if a single routine is going to execute the whole JPEG -compression sequence. Otherwise it can be static or allocated from malloc(). - -You will also need a structure representing a JPEG error handler. The part -of this that the library cares about is a "struct jpeg_error_mgr". If you -are providing your own error handler, you'll typically want to embed the -jpeg_error_mgr struct in a larger structure; this is discussed later under -"Error handling". For now we'll assume you are just using the default error -handler. The default error handler will print JPEG error/warning messages -on stderr, and it will call exit() if a fatal error occurs. - -You must initialize the error handler structure, store a pointer to it into -the JPEG object's "err" field, and then call jpeg_create_compress() to -initialize the rest of the JPEG object. - -Typical code for this step, if you are using the default error handler, is - - struct jpeg_compress_struct cinfo; - struct jpeg_error_mgr jerr; - ... - cinfo.err = jpeg_std_error(&jerr); - jpeg_create_compress(&cinfo); - -jpeg_create_compress allocates a small amount of memory, so it could fail -if you are out of memory. In that case it will exit via the error handler; -that's why the error handler must be initialized first. - - -2. Specify the destination for the compressed data (eg, a file). - -As previously mentioned, the JPEG library delivers compressed data to a -"data destination" module. The library includes one data destination -module which knows how to write to a stdio stream. You can use your own -destination module if you want to do something else, as discussed later. - -If you use the standard destination module, you must open the target stdio -stream beforehand. Typical code for this step looks like: - - FILE * outfile; - ... - if ((outfile = fopen(filename, "wb")) == NULL) { - fprintf(stderr, "can't open %s\n", filename); - exit(1); - } - jpeg_stdio_dest(&cinfo, outfile); - -where the last line invokes the standard destination module. - -WARNING: it is critical that the binary compressed data be delivered to the -output file unchanged. On non-Unix systems the stdio library may perform -newline translation or otherwise corrupt binary data. To suppress this -behavior, you may need to use a "b" option to fopen (as shown above), or use -setmode() or another routine to put the stdio stream in binary mode. See -cjpeg.c and djpeg.c for code that has been found to work on many systems. - -You can select the data destination after setting other parameters (step 3), -if that's more convenient. You may not change the destination between -calling jpeg_start_compress() and jpeg_finish_compress(). - - -3. Set parameters for compression, including image size & colorspace. - -You must supply information about the source image by setting the following -fields in the JPEG object (cinfo structure): - - image_width Width of image, in pixels - image_height Height of image, in pixels - input_components Number of color channels (samples per pixel) - in_color_space Color space of source image - -The image dimensions are, hopefully, obvious. JPEG supports image dimensions -of 1 to 64K pixels in either direction. The input color space is typically -RGB or grayscale, and input_components is 3 or 1 accordingly. (See "Special -color spaces", later, for more info.) The in_color_space field must be -assigned one of the J_COLOR_SPACE enum constants, typically JCS_RGB or -JCS_GRAYSCALE. - -JPEG has a large number of compression parameters that determine how the -image is encoded. Most applications don't need or want to know about all -these parameters. You can set all the parameters to reasonable defaults by -calling jpeg_set_defaults(); then, if there are particular values you want -to change, you can do so after that. The "Compression parameter selection" -section tells about all the parameters. - -You must set in_color_space correctly before calling jpeg_set_defaults(), -because the defaults depend on the source image colorspace. However the -other three source image parameters need not be valid until you call -jpeg_start_compress(). There's no harm in calling jpeg_set_defaults() more -than once, if that happens to be convenient. - -Typical code for a 24-bit RGB source image is - - cinfo.image_width = Width; /* image width and height, in pixels */ - cinfo.image_height = Height; - cinfo.input_components = 3; /* # of color components per pixel */ - cinfo.in_color_space = JCS_RGB; /* colorspace of input image */ - - jpeg_set_defaults(&cinfo); - /* Make optional parameter settings here */ - - -4. jpeg_start_compress(...); - -After you have established the data destination and set all the necessary -source image info and other parameters, call jpeg_start_compress() to begin -a compression cycle. This will initialize internal state, allocate working -storage, and emit the first few bytes of the JPEG datastream header. - -Typical code: - - jpeg_start_compress(&cinfo, TRUE); - -The "TRUE" parameter ensures that a complete JPEG interchange datastream -will be written. This is appropriate in most cases. If you think you might -want to use an abbreviated datastream, read the section on abbreviated -datastreams, below. - -Once you have called jpeg_start_compress(), you may not alter any JPEG -parameters or other fields of the JPEG object until you have completed -the compression cycle. - - -5. while (scan lines remain to be written) - jpeg_write_scanlines(...); - -Now write all the required image data by calling jpeg_write_scanlines() -one or more times. You can pass one or more scanlines in each call, up -to the total image height. In most applications it is convenient to pass -just one or a few scanlines at a time. The expected format for the passed -data is discussed under "Data formats", above. - -Image data should be written in top-to-bottom scanline order. The JPEG spec -contains some weasel wording about how top and bottom are application-defined -terms (a curious interpretation of the English language...) but if you want -your files to be compatible with everyone else's, you WILL use top-to-bottom -order. If the source data must be read in bottom-to-top order, you can use -the JPEG library's virtual array mechanism to invert the data efficiently. -Examples of this can be found in the sample application cjpeg. - -The library maintains a count of the number of scanlines written so far -in the next_scanline field of the JPEG object. Usually you can just use -this variable as the loop counter, so that the loop test looks like -"while (cinfo.next_scanline < cinfo.image_height)". - -Code for this step depends heavily on the way that you store the source data. -example.c shows the following code for the case of a full-size 2-D source -array containing 3-byte RGB pixels: - - JSAMPROW row_pointer[1]; /* pointer to a single row */ - int row_stride; /* physical row width in buffer */ - - row_stride = image_width * 3; /* JSAMPLEs per row in image_buffer */ - - while (cinfo.next_scanline < cinfo.image_height) { - row_pointer[0] = & image_buffer[cinfo.next_scanline * row_stride]; - jpeg_write_scanlines(&cinfo, row_pointer, 1); - } - -jpeg_write_scanlines() returns the number of scanlines actually written. -This will normally be equal to the number passed in, so you can usually -ignore the return value. It is different in just two cases: - * If you try to write more scanlines than the declared image height, - the additional scanlines are ignored. - * If you use a suspending data destination manager, output buffer overrun - will cause the compressor to return before accepting all the passed lines. - This feature is discussed under "I/O suspension", below. The normal - stdio destination manager will NOT cause this to happen. -In any case, the return value is the same as the change in the value of -next_scanline. - - -6. jpeg_finish_compress(...); - -After all the image data has been written, call jpeg_finish_compress() to -complete the compression cycle. This step is ESSENTIAL to ensure that the -last bufferload of data is written to the data destination. -jpeg_finish_compress() also releases working memory associated with the JPEG -object. - -Typical code: - - jpeg_finish_compress(&cinfo); - -If using the stdio destination manager, don't forget to close the output -stdio stream if necessary. - -If you have requested a multi-pass operating mode, such as Huffman code -optimization, jpeg_finish_compress() will perform the additional passes using -data buffered by the first pass. In this case jpeg_finish_compress() may take -quite a while to complete. With the default compression parameters, this will -not happen. - -It is an error to call jpeg_finish_compress() before writing the necessary -total number of scanlines. If you wish to abort compression, call -jpeg_abort() as discussed below. - -After completing a compression cycle, you may dispose of the JPEG object -as discussed next, or you may use it to compress another image. In that case -return to step 2, 3, or 4 as appropriate. If you do not change the -destination manager, the new datastream will be written to the same target. -If you do not change any JPEG parameters, the new datastream will be written -with the same parameters as before. Note that you can change the input image -dimensions freely between cycles, but if you change the input colorspace, you -should call jpeg_set_defaults() to adjust for the new colorspace; and then -you'll need to repeat all of step 3. - - -7. Release the JPEG compression object. - -When you are done with a JPEG compression object, destroy it by calling -jpeg_destroy_compress(). This will free all subsidiary memory. Or you can -call jpeg_destroy() which works for either compression or decompression -objects --- this may be more convenient if you are sharing code between -compression and decompression cases. (Actually, these routines are equivalent -except for the declared type of the passed pointer. To avoid gripes from -ANSI C compilers, pass a j_common_ptr to jpeg_destroy().) - -If you allocated the jpeg_compress_struct structure from malloc(), freeing -it is your responsibility --- jpeg_destroy() won't. Ditto for the error -handler structure. - -Typical code: - - jpeg_destroy_compress(&cinfo); - - -8. Aborting. - -If you decide to abort a compression cycle before finishing, you can clean up -in either of two ways: - -* If you don't need the JPEG object any more, just call - jpeg_destroy_compress() or jpeg_destroy() to release memory. This is - legitimate at any point after calling jpeg_create_compress() --- in fact, - it's safe even if jpeg_create_compress() fails. - -* If you want to re-use the JPEG object, call jpeg_abort_compress(), or - jpeg_abort() which works on both compression and decompression objects. - This will return the object to an idle state, releasing any working memory. - jpeg_abort() is allowed at any time after successful object creation. - -Note that cleaning up the data destination, if required, is your -responsibility. - - -Decompression details ---------------------- - -Here we revisit the JPEG decompression outline given in the overview. - -1. Allocate and initialize a JPEG decompression object. - -This is just like initialization for compression, as discussed above, -except that the object is a "struct jpeg_decompress_struct" and you -call jpeg_create_decompress(). Error handling is exactly the same. - -Typical code: - - struct jpeg_decompress_struct cinfo; - struct jpeg_error_mgr jerr; - ... - cinfo.err = jpeg_std_error(&jerr); - jpeg_create_decompress(&cinfo); - -(Both here and in the IJG code, we usually use variable name "cinfo" for -both compression and decompression objects.) - - -2. Specify the source of the compressed data (eg, a file). - -As previously mentioned, the JPEG library reads compressed data from a "data -source" module. The library includes one data source module which knows how -to read from a stdio stream. You can use your own source module if you want -to do something else, as discussed later. - -If you use the standard source module, you must open the source stdio stream -beforehand. Typical code for this step looks like: - - FILE * infile; - ... - if ((infile = fopen(filename, "rb")) == NULL) { - fprintf(stderr, "can't open %s\n", filename); - exit(1); - } - jpeg_stdio_src(&cinfo, infile); - -where the last line invokes the standard source module. - -WARNING: it is critical that the binary compressed data be read unchanged. -On non-Unix systems the stdio library may perform newline translation or -otherwise corrupt binary data. To suppress this behavior, you may need to use -a "b" option to fopen (as shown above), or use setmode() or another routine to -put the stdio stream in binary mode. See cjpeg.c and djpeg.c for code that -has been found to work on many systems. - -You may not change the data source between calling jpeg_read_header() and -jpeg_finish_decompress(). If you wish to read a series of JPEG images from -a single source file, you should repeat the jpeg_read_header() to -jpeg_finish_decompress() sequence without reinitializing either the JPEG -object or the data source module; this prevents buffered input data from -being discarded. - - -3. Call jpeg_read_header() to obtain image info. - -Typical code for this step is just - - jpeg_read_header(&cinfo, TRUE); - -This will read the source datastream header markers, up to the beginning -of the compressed data proper. On return, the image dimensions and other -info have been stored in the JPEG object. The application may wish to -consult this information before selecting decompression parameters. - -More complex code is necessary if - * A suspending data source is used --- in that case jpeg_read_header() - may return before it has read all the header data. See "I/O suspension", - below. The normal stdio source manager will NOT cause this to happen. - * Abbreviated JPEG files are to be processed --- see the section on - abbreviated datastreams. Standard applications that deal only in - interchange JPEG files need not be concerned with this case either. - -It is permissible to stop at this point if you just wanted to find out the -image dimensions and other header info for a JPEG file. In that case, -call jpeg_destroy() when you are done with the JPEG object, or call -jpeg_abort() to return it to an idle state before selecting a new data -source and reading another header. - - -4. Set parameters for decompression. - -jpeg_read_header() sets appropriate default decompression parameters based on -the properties of the image (in particular, its colorspace). However, you -may well want to alter these defaults before beginning the decompression. -For example, the default is to produce full color output from a color file. -If you want colormapped output you must ask for it. Other options allow the -returned image to be scaled and allow various speed/quality tradeoffs to be -selected. "Decompression parameter selection", below, gives details. - -If the defaults are appropriate, nothing need be done at this step. - -Note that all default values are set by each call to jpeg_read_header(). -If you reuse a decompression object, you cannot expect your parameter -settings to be preserved across cycles, as you can for compression. -You must adjust parameter values each time. - - -5. jpeg_start_decompress(...); - -Once the parameter values are satisfactory, call jpeg_start_decompress() to -begin decompression. This will initialize internal state, allocate working -memory, and prepare for returning data. - -Typical code is just - - jpeg_start_decompress(&cinfo); - -If you have requested a multi-pass operating mode, such as 2-pass color -quantization, jpeg_start_decompress() will do everything needed before data -output can begin. In this case jpeg_start_decompress() may take quite a while -to complete. With a single-scan (fully interleaved) JPEG file and default -decompression parameters, this will not happen; jpeg_start_decompress() will -return quickly. - -After this call, the final output image dimensions, including any requested -scaling, are available in the JPEG object; so is the selected colormap, if -colormapped output has been requested. Useful fields include - - output_width image width and height, as scaled - output_height - out_color_components # of color components in out_color_space - output_components # of color components returned per pixel - colormap the selected colormap, if any - actual_number_of_colors number of entries in colormap - -output_components is 1 (a colormap index) when quantizing colors; otherwise it -equals out_color_components. It is the number of JSAMPLE values that will be -emitted per pixel in the output arrays. - -Typically you will need to allocate data buffers to hold the incoming image. -You will need output_width * output_components JSAMPLEs per scanline in your -output buffer, and a total of output_height scanlines will be returned. - -Note: if you are using the JPEG library's internal memory manager to allocate -data buffers (as djpeg does), then the manager's protocol requires that you -request large buffers *before* calling jpeg_start_decompress(). This is a -little tricky since the output_XXX fields are not normally valid then. You -can make them valid by calling jpeg_calc_output_dimensions() after setting the -relevant parameters (scaling, output color space, and quantization flag). - - -6. while (scan lines remain to be read) - jpeg_read_scanlines(...); - -Now you can read the decompressed image data by calling jpeg_read_scanlines() -one or more times. At each call, you pass in the maximum number of scanlines -to be read (ie, the height of your working buffer); jpeg_read_scanlines() -will return up to that many lines. The return value is the number of lines -actually read. The format of the returned data is discussed under "Data -formats", above. - -Image data is returned in top-to-bottom scanline order. If you must write -out the image in bottom-to-top order, you can use the JPEG library's virtual -array mechanism to invert the data efficiently. Examples of this can be -found in the sample application djpeg. - -The library maintains a count of the number of scanlines returned so far -in the output_scanline field of the JPEG object. Usually you can just use -this variable as the loop counter, so that the loop test looks like -"while (cinfo.output_scanline < cinfo.output_height)". (Note that the test -should NOT be against image_height, unless you never use scaling. The -image_height field is the height of the original unscaled image.) - -If you don't use a suspending data source, it is safe to assume that -jpeg_read_scanlines() reads at least one scanline per call, until the -bottom of the image has been reached. If you use a buffer larger than one -scanline, it is NOT safe to assume that jpeg_read_scanlines() fills it. -In any case, the return value is the same as the change in the value of -output_scanline. - - -7. jpeg_finish_decompress(...); - -After all the image data has been read, call jpeg_finish_decompress() to -complete the decompression cycle. This causes working memory associated -with the JPEG object to be released. - -Typical code: - - jpeg_finish_decompress(&cinfo); - -If using the stdio source manager, don't forget to close the source stdio -stream if necessary. - -It is an error to call jpeg_finish_decompress() before reading the correct -total number of scanlines. If you wish to abort compression, call -jpeg_abort() as discussed below. - -After completing a decompression cycle, you may dispose of the JPEG object as -discussed next, or you may use it to decompress another image. In that case -return to step 2 or 3 as appropriate. If you do not change the source -manager, the next image will be read from the same source. - - -8. Release the JPEG decompression object. - -When you are done with a JPEG decompression object, destroy it by calling -jpeg_destroy_decompress() or jpeg_destroy(). The previous discussion of -destroying compression objects applies here too. - -Typical code: - - jpeg_destroy_decompress(&cinfo); - - -9. Aborting. - -You can abort a decompression cycle by calling jpeg_destroy_decompress() or -jpeg_destroy() if you don't need the JPEG object any more, or -jpeg_abort_decompress() or jpeg_abort() if you want to reuse the object. -The previous discussion of aborting compression cycles applies here too. - - -Mechanics of usage: include files, linking, etc ------------------------------------------------ - -Applications using the JPEG library should include the header file jpeglib.h -to obtain declarations of data types and routines. Before including -jpeglib.h, include system headers that define at least the typedefs FILE and -size_t. On ANSI-conforming systems, including is sufficient; on -older Unix systems, you may need to define size_t. - -If the application needs to refer to individual JPEG library error codes, also -include jerror.h to define those symbols. - -jpeglib.h indirectly includes the files jconfig.h and jmorecfg.h. If you are -installing the JPEG header files in a system directory, you will want to -install all four files: jpeglib.h, jerror.h, jconfig.h, jmorecfg.h. - -The most convenient way to include the JPEG code into your executable program -is to prepare a library file ("libjpeg.a", or a corresponding name on non-Unix -machines) and reference it at your link step. If you use only half of the -library (only compression or only decompression), only that much code will be -included from the library, unless your linker is hopelessly brain-damaged. -The supplied makefiles build libjpeg.a automatically (see install.doc). - -On some systems your application may need to set up a signal handler to ensure -that temporary files are deleted if the program is interrupted. This is most -critical if you are on MS-DOS and use the jmemdos.c memory manager back end; -it will try to grab extended memory for temp files, and that space will NOT be -freed automatically. See cjpeg.c or djpeg.c for an example signal handler. - -It may be worth pointing out that the core JPEG library does not actually -require the stdio library: only the default source/destination managers and -error handler need it. You can use the library in a stdio-less environment -if you replace those modules and use jmemnobs.c (or another memory manager of -your own devising). More info about the minimum system library requirements -may be found in jinclude.h. - - -ADVANCED FEATURES -================= - -Compression parameter selection -------------------------------- - -This section describes all the optional parameters you can set for JPEG -compression, as well as the "helper" routines provided to assist in this -task. Proper setting of some parameters requires detailed understanding -of the JPEG standard; if you don't know what a parameter is for, it's best -not to mess with it! See REFERENCES in the README file for pointers to -more info about JPEG. - -It's a good idea to call jpeg_set_defaults() first, even if you plan to set -all the parameters; that way your code is more likely to work with future JPEG -libraries that have additional parameters. For the same reason, we recommend -you use a helper routine where one is provided, in preference to twiddling -cinfo fields directly. - -The helper routines are: - -jpeg_set_defaults (j_compress_ptr cinfo) - This routine sets all JPEG parameters to reasonable defaults, using - only the input image's color space (field in_color_space, which must - already be set in cinfo). Many applications will only need to use - this routine and perhaps jpeg_set_quality(). - -jpeg_set_colorspace (j_compress_ptr cinfo, J_COLOR_SPACE colorspace) - Sets the JPEG file's colorspace (field jpeg_color_space) as specified, - and sets other color-space-dependent parameters appropriately. See - "Special color spaces", below, before using this. A large number of - parameters, including all per-component parameters, are set by this - routine; if you want to twiddle individual parameters you should call - jpeg_set_colorspace() before rather than after. - -jpeg_default_colorspace (j_compress_ptr cinfo) - Selects an appropriate JPEG colorspace based on cinfo->in_color_space, - and calls jpeg_set_colorspace(). This is actually a subroutine of - jpeg_set_defaults(). It's broken out in case you want to change - just the colorspace-dependent JPEG parameters. - -jpeg_set_quality (j_compress_ptr cinfo, int quality, boolean force_baseline) - Constructs JPEG quantization tables appropriate for the indicated - quality setting. The quality value is expressed on the 0..100 scale - recommended by IJG (cjpeg's "-quality" switch uses this routine). - Note that the exact mapping from quality values to tables may change - in future IJG releases as more is learned about DCT quantization. - If the force_baseline parameter is TRUE, then the quantization table - entries are constrained to the range 1..255 for full JPEG baseline - compatibility. In the current implementation, this only makes a - difference for quality settings below 25, and it effectively prevents - very small/low quality files from being generated. The IJG decoder - is capable of reading the non-baseline files generated at low quality - settings when force_baseline is FALSE, but other decoders may not be. - -jpeg_set_linear_quality (j_compress_ptr cinfo, int scale_factor, - boolean force_baseline) - Same as jpeg_set_quality() except that the generated tables are the - sample tables given in the JPEC spec section K.1, multiplied by the - specified scale factor (which is expressed as a percentage; thus - scale_factor = 100 reproduces the spec's tables). Note that larger - scale factors give lower quality. This entry point is useful for - conforming to the Adobe PostScript DCT conventions, but we do not - recommend linear scaling as a user-visible quality scale otherwise. - force_baseline again constrains the computed table entries to 1..255. - -int jpeg_quality_scaling (int quality) - Converts a value on the IJG-recommended quality scale to a linear - scaling percentage. Note that this routine may change or go away - in future releases --- IJG may choose to adopt a scaling method that - can't be expressed as a simple scalar multiplier, in which case the - premise of this routine collapses. Caveat user. - -jpeg_add_quant_table (j_compress_ptr cinfo, int which_tbl, - const unsigned int *basic_table, - int scale_factor, boolean force_baseline)); - Allows an arbitrary quantization table to be created. which_tbl - indicates which table slot to fill. basic_table points to an array - of 64 unsigned ints given in JPEG zigzag order. These values are - multiplied by scale_factor/100 and then clamped to the range 1..65535 - (or to 1..255 if force_baseline is TRUE). - - -Compression parameters (cinfo fields) include: - -boolean optimize_coding - TRUE causes the compressor to compute optimal Huffman coding tables - for the image. This requires an extra pass over the data and - therefore costs a good deal of space and time. The default is - FALSE, which tells the compressor to use the supplied or default - Huffman tables. In most cases optimal tables save only a few percent - of file size compared to the default tables. Note that when this is - TRUE, you need not supply Huffman tables at all, and any you do - supply will be overwritten. - -int smoothing_factor - If non-zero, the input image is smoothed; the value should be 1 for - minimal smoothing to 100 for maximum smoothing. Consult jcsample.c - for details of the smoothing algorithm. The default is zero. - -J_DCT_METHOD dct_method - Selects the algorithm used for the DCT step. Choices are: - JDCT_ISLOW: slow but accurate integer algorithm - JDCT_IFAST: faster, less accurate integer method - JDCT_FLOAT: floating-point method - JDCT_DEFAULT: default method (normally JDCT_ISLOW) - JDCT_FASTEST: fastest method (normally JDCT_IFAST) - The floating-point method is the most accurate, but may give slightly - different results on different machines due to varying roundoff - behavior. The integer methods should give the same results on all - machines. On machines with sufficiently fast FP hardware, the - floating-point method may also be the fastest. The IFAST method is - considerably less accurate than the other two; its use is not - recommended if high quality is a concern. JDCT_DEFAULT and - JDCT_FASTEST are macros configurable by each installation. - -unsigned int restart_interval -int restart_in_rows - To emit restart markers in the JPEG file, set one of these nonzero. - Set restart_interval to specify the exact interval in MCU blocks. - Set restart_in_rows to specify the interval in MCU rows. (If - restart_in_rows is not 0, then restart_interval is set after the - image width in MCUs is computed.) Defaults are zero (no restarts). - -J_COLOR_SPACE jpeg_color_space -int num_components - The JPEG color space and corresponding number of components; see - "Special color spaces", below, for more info. We recommend using - jpeg_set_color_space() if you want to change these. - -boolean write_JFIF_header - If TRUE, a JFIF APP0 marker is emitted. jpeg_set_defaults() and - jpeg_set_colorspace() set this TRUE if a JFIF-legal JPEG color space - (ie, YCbCr or grayscale) is selected, otherwise FALSE. - -UINT8 density_unit -UINT16 X_density -UINT16 Y_density - The resolution information to be written into the JFIF marker; - not used otherwise. density_unit may be 0 for unknown, - 1 for dots/inch, or 2 for dots/cm. The default values are 0,1,1 - indicating square pixels of unknown size. - -boolean write_Adobe_marker - If TRUE, an Adobe APP14 marker is emitted. jpeg_set_defaults() and - jpeg_set_colorspace() set this TRUE if JPEG color space RGB, CMYK, - or YCCK is selected, otherwise FALSE. It is generally a bad idea - to set both write_JFIF_header and write_Adobe_marker. In fact, - you probably shouldn't change the default settings at all --- the - default behavior ensures that the JPEG file's color space can be - recognized by the decoder. - -JQUANT_TBL * quant_tbl_ptrs[NUM_QUANT_TBLS] - Pointers to coefficient quantization tables, one per table slot, - or NULL if no table is defined for a slot. Usually these should - be set via one of the above helper routines; jpeg_add_quant_table() - is general enough to define any quantization table. The other - routines will set up table slot 0 for luminance quality and table - slot 1 for chrominance. - -JHUFF_TBL * dc_huff_tbl_ptrs[NUM_HUFF_TBLS] -JHUFF_TBL * ac_huff_tbl_ptrs[NUM_HUFF_TBLS] - Pointers to Huffman coding tables, one per table slot, or NULL if - no table is defined for a slot. Slots 0 and 1 are filled with the - JPEG sample tables by jpeg_set_defaults(). If you need to allocate - more table structures, jpeg_alloc_huff_table() may be used. - Note that optimal Huffman tables can be computed for an image - by setting optimize_coding, as discussed above; there's seldom - any need to mess with providing your own Huffman tables. - -There are some additional cinfo fields which are not documented here -because you currently can't change them; for example, you can't set -arith_code TRUE because arithmetic coding is unsupported. - - -Per-component parameters are stored in the struct cinfo.comp_info[i] for -component number i. Note that components here refer to components of the -JPEG color space, *not* the source image color space. A suitably large -comp_info[] array is allocated by jpeg_set_defaults(); if you choose not -to use that routine, it's up to you to allocate the array. - -int component_id - The one-byte identifier code to be recorded in the JPEG file for - this component. For the standard color spaces, we recommend you - leave the default values alone. - -int h_samp_factor -int v_samp_factor - Horizontal and vertical sampling factors for the component; must - be 1..4 according to the JPEG standard. Note that larger sampling - factors indicate a higher-resolution component; many people find - this behavior quite unintuitive. The default values are 2,2 for - luminance components and 1,1 for chrominance components, except - for grayscale where 1,1 is used. - -int quant_tbl_no - Quantization table number for component. The default value is - 0 for luminance components and 1 for chrominance components. - -int dc_tbl_no -int ac_tbl_no - DC and AC entropy coding table numbers. The default values are - 0 for luminance components and 1 for chrominance components. - -int component_index - Must equal the component's index in comp_info[]. - - -Decompression parameter selection ---------------------------------- - -Decompression parameter selection is somewhat simpler than compression -parameter selection, since all of the JPEG internal parameters are -recorded in the source file and need not be supplied by the application. -(Unless you are working with abbreviated files, in which case see -"Abbreviated datastreams", below.) Decompression parameters control -the postprocessing done on the image to deliver it in a format suitable -for the application's use. Many of the parameters control speed/quality -tradeoffs, in which faster decompression may be obtained at the price of -a poorer-quality image. The defaults select the highest quality (slowest) -processing. - -The following fields in the JPEG object are set by jpeg_read_header() and -may be useful to the application in choosing decompression parameters: - -JDIMENSION image_width Width and height of image -JDIMENSION image_height -int num_components Number of color components -J_COLOR_SPACE jpeg_color_space Colorspace of image -boolean saw_JFIF_marker TRUE if a JFIF APP0 marker was seen - UINT8 density_unit Resolution data from JFIF marker - UINT16 X_density - UINT16 Y_density -boolean saw_Adobe_marker TRUE if an Adobe APP14 marker was seen - UINT8 Adobe_transform Color transform code from Adobe marker - -The JPEG color space, unfortunately, is something of a guess since the JPEG -standard proper does not provide a way to record it. In practice most files -adhere to the JFIF or Adobe conventions, and the decoder will recognize these -correctly. See "Special color spaces", below, for more info. - - -The decompression parameters that determine the basic properties of the -returned image are: - -J_COLOR_SPACE out_color_space - Output color space. jpeg_read_header() sets an appropriate default - based on jpeg_color_space; typically it will be RGB or grayscale. - The application can change this field to request output in a different - colorspace. For example, set it to JCS_GRAYSCALE to get grayscale - output from a color file. (This is useful for previewing: grayscale - output is faster than full color since the color components need not - be processed.) Note that not all possible color space transforms are - currently implemented; you may need to extend jdcolor.c if you want an - unusual conversion. - -unsigned int scale_num, scale_denom - Scale the image by the fraction scale_num/scale_denom. Default is - 1/1, or no scaling. Currently, the only supported scaling ratios - are 1/1, 1/2, 1/4, and 1/8. (The library design allows for arbitrary - scaling ratios but this is not likely to be implemented any time soon.) - Smaller scaling ratios permit significantly faster decoding since - fewer pixels need be processed and a simpler IDCT method can be used. - -boolean quantize_colors - If set TRUE, colormapped output will be delivered. Default is FALSE, - meaning that full-color output will be delivered. - -The next three parameters are relevant only if quantize_colors is TRUE. - -int desired_number_of_colors - Maximum number of colors to use in generating a library-supplied color - map (the actual number of colors is returned in a different field). - Default 256. Ignored when the application supplies its own color map. - -boolean two_pass_quantize - If TRUE, an extra pass over the image is made to select a custom color - map for the image. This usually looks a lot better than the one-size- - fits-all colormap that is used otherwise. Default is TRUE. Ignored - when the application supplies its own color map. - -J_DITHER_MODE dither_mode - Selects color dithering method. Supported values are: - JDITHER_NONE no dithering: fast, very low quality - JDITHER_ORDERED ordered dither: moderate speed and quality - JDITHER_FS Floyd-Steinberg dither: slow, high quality - Default is JDITHER_FS. (At present, ordered dither is implemented - only in the single-pass, standard-colormap case. If you ask for - ordered dither when two_pass_quantize is TRUE or when you supply - an external color map, you'll get F-S dithering.) - -When quantize_colors is TRUE, the target color map is described by the next -two fields. colormap is set to NULL by jpeg_read_header(). The application -can supply a color map by setting colormap non-NULL and setting -actual_number_of_colors to the map size. Otherwise, jpeg_start_decompress() -selects a suitable color map and sets these two fields itself. -[Implementation restriction: at present, an externally supplied colormap is -only accepted for 3-component output color spaces.] - -JSAMPARRAY colormap - The color map, represented as a 2-D pixel array of out_color_components - rows and actual_number_of_colors columns. Ignored if not quantizing. - -int actual_number_of_colors - The number of colors in the color map. - -Additional decompression parameters that the application may set include: - -J_DCT_METHOD dct_method - Selects the algorithm used for the DCT step. Choices are the same - as described above for compression. - -boolean do_fancy_upsampling - If TRUE, do careful upsampling of chroma components. If FALSE, - a faster but sloppier method is used. Default is TRUE. The visual - impact of the sloppier method is often very small. - - -The output image dimensions are given by the following fields. These are -computed from the source image dimensions and the decompression parameters -by jpeg_start_decompress(). You can also call jpeg_calc_output_dimensions() -to obtain the values that will result from the current parameter settings. -This can be useful if you are trying to pick a scaling ratio that will get -close to a desired target size. It's also important if you are using the -JPEG library's memory manager to allocate output buffer space, because you -are supposed to request such buffers *before* jpeg_start_decompress(). - -JDIMENSION output_width Actual dimensions of output image. -JDIMENSION output_height -int out_color_components Number of color components in out_color_space. -int output_components Number of color components returned. -int rec_outbuf_height Recommended height of scanline buffer. - -When quantizing colors, output_components is 1, indicating a single color map -index per pixel. Otherwise it equals out_color_components. The output arrays -are required to be output_width * output_components JSAMPLEs wide. - -rec_outbuf_height is the recommended minimum height (in scanlines) of the -buffer passed to jpeg_read_scanlines(). If the buffer is smaller, the -library will still work, but time will be wasted due to unnecessary data -copying. In high-quality modes, rec_outbuf_height is always 1, but some -faster, lower-quality modes set it to larger values (typically 2 to 4). -If you are going to ask for a high-speed processing mode, you may as well -go to the trouble of honoring rec_outbuf_height so as to avoid data copying. - - -Special color spaces --------------------- - -The JPEG standard itself is "color blind" and doesn't specify any particular -color space. It is customary to convert color data to a luminance/chrominance -color space before compressing, since this permits greater compression. The -existing de-facto JPEG file format standards specify YCbCr or grayscale data -(JFIF), or grayscale, RGB, YCbCr, CMYK, or YCCK (Adobe). For special -applications such as multispectral images, other color spaces can be used, -but it must be understood that such files will be unportable. - -The JPEG library can handle the most common colorspace conversions (namely -RGB <=> YCbCr and CMYK <=> YCCK). It can also deal with data of an unknown -color space, passing it through without conversion. If you deal extensively -with an unusual color space, you can easily extend the library to understand -additional color spaces and perform appropriate conversions. - -For compression, the source data's color space is specified by field -in_color_space. This is transformed to the JPEG file's color space given -by jpeg_color_space. jpeg_set_defaults() chooses a reasonable JPEG color -space depending on in_color_space, but you can override this by calling -jpeg_set_colorspace(). Of course you must select a supported transformation. -jccolor.c currently supports the following transformations: - RGB => YCbCr - RGB => GRAYSCALE - YCbCr => GRAYSCALE - CMYK => YCCK -plus the null transforms: GRAYSCALE => GRAYSCALE, RGB => RGB, -YCbCr => YCbCr, CMYK => CMYK, YCCK => YCCK, and UNKNOWN => UNKNOWN. - -The de-facto file format standards (JFIF and Adobe) specify APPn markers that -indicate the color space of the JPEG file. It is important to ensure that -these are written correctly, or omitted if the JPEG file's color space is not -one of the ones supported by the de-facto standards. jpeg_set_colorspace() -will set the compression parameters to include or omit the APPn markers -properly, so long as it is told the truth about the JPEG color space. -For example, if you are writing some random 3-component color space without -conversion, don't try to fake out the library by setting in_color_space and -jpeg_color_space to JCS_YCbCr; use JCS_UNKNOWN. You may want to write an -APPn marker of your own devising to identify the colorspace --- see "Special -markers", below. - -When told that the color space is UNKNOWN, the library will default to using -luminance-quality compression parameters for all color components. You may -well want to change these parameters. See the source code for -jpeg_set_colorspace(), in jcparam.c, for details. - -For decompression, the JPEG file's color space is given in jpeg_color_space, -and this is transformed to the output color space out_color_space. -jpeg_read_header's setting of jpeg_color_space can be relied on if the file -conforms to JFIF or Adobe conventions, but otherwise it is no better than a -guess. If you know the JPEG file's color space for certain, you can override -jpeg_read_header's guess by setting jpeg_color_space. jpeg_read_header also -selects a default output color space based on (its guess of) jpeg_color_space; -set out_color_space to override this. Again, you must select a supported -transformation. jdcolor.c currently supports - YCbCr => GRAYSCALE - YCbCr => RGB - YCCK => CMYK -as well as the null transforms. - -The two-pass color quantizer, jquant2.c, is specialized to handle RGB data -(it weights distances appropriately for RGB colors). You'll need to modify -the code if you want to use it for non-RGB output color spaces. Note that -jquant2.c is used to map to an application-supplied colormap as well as for -the normal two-pass colormap selection process. - -CAUTION: it appears that Adobe Photoshop writes inverted data in CMYK JPEG -files: 0 represents 100% ink coverage, rather than 0% ink as you'd expect. -This is arguably a bug in Photoshop, but if you need to work with Photoshop -CMYK files, you will have to deal with it in your application. We cannot -"fix" this in the library by inverting the data during the CMYK<=>YCCK -transform, because that would break other applications, notably Ghostscript. -Photoshop versions prior to 3.0 write EPS files containing JPEG-encoded CMYK -data in the same inverted-YCCK representation used in bare JPEG files, but -the surrounding PostScript code performs an inversion using the PS image -operator. I am told that Photoshop 3.0 will write uninverted YCCK in -EPS/JPEG files, and will omit the PS-level inversion. (But the data -polarity used in bare JPEG files will not change in 3.0.) In either case, -the JPEG library must not invert the data itself, or else Ghostscript would -read these EPS files incorrectly. - - -Error handling --------------- - -When the default error handler is used, any error detected inside the JPEG -routines will cause a message to be printed on stderr, followed by exit(). -You can supply your own error handling routines to override this behavior -and to control the treatment of nonfatal warnings and trace/debug messages. -The file example.c illustrates the most common case, which is to have the -application regain control after an error rather than exiting. - -The JPEG library never writes any message directly; it always goes through -the error handling routines. Three classes of messages are recognized: - * Fatal errors: the library cannot continue. - * Warnings: the library can continue, but the data is corrupt, and a - damaged output image is likely to result. - * Trace/informational messages. These come with a trace level indicating - the importance of the message; you can control the verbosity of the - program by adjusting the maximum trace level that will be displayed. - -You may, if you wish, simply replace the entire JPEG error handling module -(jerror.c) with your own code. However, you can avoid code duplication by -only replacing some of the routines depending on the behavior you need. -This is accomplished by calling jpeg_std_error() as usual, but then overriding -some of the method pointers in the jpeg_error_mgr struct, as illustrated by -example.c. - -All of the error handling routines will receive a pointer to the JPEG object -(a j_common_ptr which points to either a jpeg_compress_struct or a -jpeg_decompress_struct; if you need to tell which, test the is_decompressor -field). This struct includes a pointer to the error manager struct in its -"err" field. Frequently, custom error handler routines will need to access -additional data which is not known to the JPEG library or the standard error -handler. The most convenient way to do this is to embed either the JPEG -object or the jpeg_error_mgr struct in a larger structure that contains -additional fields; then casting the passed pointer provides access to the -additional fields. Again, see example.c for one way to do it. - -The individual methods that you might wish to override are: - -error_exit (j_common_ptr cinfo) - Receives control for a fatal error. Information sufficient to - generate the error message has been stored in cinfo->err; call - output_message to display it. Control must NOT return to the caller; - generally this routine will exit() or longjmp() somewhere. - Typically you would override this routine to get rid of the exit() - default behavior. Note that if you continue processing, you should - clean up the JPEG object with jpeg_abort() or jpeg_destroy(). - -output_message (j_common_ptr cinfo) - Actual output of any JPEG message. Override this to send messages - somewhere other than stderr. Note that this method does not know - how to generate a message, only where to send it. - -format_message (j_common_ptr cinfo, char * buffer) - Constructs a readable error message string based on the error info - stored in cinfo->err. This method is called by output_message. Few - applications should need to override this method. One possible - reason for doing so is to implement dynamic switching of error message - language. - -emit_message (j_common_ptr cinfo, int msg_level) - Decide whether or not to emit a warning or trace message; if so, - calls output_message. The main reason for overriding this method - would be to abort on warnings. msg_level is -1 for warnings, - 0 and up for trace messages. - -Only error_exit() and emit_message() are called from the rest of the JPEG -library; the other two are internal to the error handler. - -The actual message texts are stored in an array of strings which is pointed to -by the field err->jpeg_message_table. The messages are numbered from 0 to -err->last_jpeg_message, and it is these code numbers that are used in the -JPEG library code. You could replace the message texts (for instance, with -messages in French or German) by changing the message table pointer. See -jerror.h for the default texts. CAUTION: this table will almost certainly -change or grow from one library version to the next. - -It may be useful for an application to add its own message texts that are -handled by the same mechanism. The error handler supports a second "add-on" -message table for this purpose. To define an addon table, set the pointer -err->addon_message_table and the message numbers err->first_addon_message and -err->last_addon_message. If you number the addon messages beginning at 1000 -or so, you won't have to worry about conflicts with the library's built-in -messages. See the sample applications cjpeg/djpeg for an example of using -addon messages (the addon messages are defined in cderror.h). - -Actual invocation of the error handler is done via macros defined in jerror.h: - ERREXITn(...) for fatal errors - WARNMSn(...) for corrupt-data warnings - TRACEMSn(...) for trace and informational messages. -These macros store the message code and any additional parameters into the -error handler struct, then invoke the error_exit() or emit_message() method. -The variants of each macro are for varying numbers of additional parameters. -The additional parameters are inserted into the generated message using -standard printf() format codes. - -See jerror.h and jerror.c for further details. - - -Compressed data handling (source and destination managers) ----------------------------------------------------------- - -The JPEG compression library sends its compressed data to a "destination -manager" module. The default destination manager just writes the data to a -stdio stream, but you can provide your own manager to do something else. -Similarly, the decompression library calls a "source manager" to obtain the -compressed data; you can provide your own source manager if you want the data -to come from somewhere other than a stdio stream. - -In both cases, compressed data is processed a bufferload at a time: the -destination or source manager provides a work buffer, and the library invokes -the manager only when the buffer is filled or emptied. (You could define a -one-character buffer to force the manager to be invoked for each byte, but -that would be rather inefficient.) The buffer's size and location are -controlled by the manager, not by the library. For example, if you desired to -decompress a JPEG datastream that was all in memory, you could just make the -buffer pointer and length point to the original data in memory. Then the -buffer-reload procedure would be invoked only if the decompressor ran off the -end of the datastream, which would indicate an erroneous datastream. - -The work buffer is defined as an array of datatype JOCTET, which is generally -"char" or "unsigned char". On a machine where char is not exactly 8 bits -wide, you must define JOCTET as a wider data type and then modify the data -source and destination modules to transcribe the work arrays into 8-bit units -on external storage. - -A data destination manager struct contains a pointer and count defining the -next byte to write in the work buffer and the remaining free space: - - JOCTET * next_output_byte; /* => next byte to write in buffer */ - size_t free_in_buffer; /* # of byte spaces remaining in buffer */ - -The library increments the pointer and decrements the count until the buffer -is filled. The manager's empty_output_buffer method must reset the pointer -and count. The manager is expected to remember the buffer's starting address -and total size in private fields not visible to the library. - -A data destination manager provides three methods: - -init_destination (j_compress_ptr cinfo) - Initialize destination. This is called by jpeg_start_compress() - before any data is actually written. It must initialize - next_output_byte and free_in_buffer. free_in_buffer must be - initialized to a positive value. - -empty_output_buffer (j_compress_ptr cinfo) - This is called whenever the buffer has filled (free_in_buffer - reaches zero). In typical applications, it should write out the - *entire* buffer (use the saved start address and buffer length; - ignore the current state of next_output_byte and free_in_buffer). - Then reset the pointer & count to the start of the buffer, and - return TRUE indicating that the buffer has been dumped. - free_in_buffer must be set to a positive value when TRUE is - returned. A FALSE return should only be used when I/O suspension is - desired (this operating mode is discussed in the next section). - -term_destination (j_compress_ptr cinfo) - Terminate destination --- called by jpeg_finish_compress() after all - data has been written. In most applications, this must flush any - data remaining in the buffer. Use either next_output_byte or - free_in_buffer to determine how much data is in the buffer. - -term_destination() is NOT called by jpeg_abort() or jpeg_destroy(). If you -want the destination manager to be cleaned up during an abort, you must do it -yourself. - -You will also need code to create a jpeg_destination_mgr struct, fill in its -method pointers, and insert a pointer to the struct into the "dest" field of -the JPEG compression object. This can be done in-line in your setup code if -you like, but it's probably cleaner to provide a separate routine similar to -the jpeg_stdio_dest() routine of the supplied destination manager. - -Decompression source managers follow a parallel design, but with some -additional frammishes. The source manager struct contains a pointer and count -defining the next byte to read from the work buffer and the number of bytes -remaining: - - const JOCTET * next_input_byte; /* => next byte to read from buffer */ - size_t bytes_in_buffer; /* # of bytes remaining in buffer */ - -The library increments the pointer and decrements the count until the buffer -is emptied. The manager's fill_input_buffer method must reset the pointer and -count. In most applications, the manager must remember the buffer's starting -address and total size in private fields not visible to the library. - -A data source manager provides five methods: - -init_source (j_decompress_ptr cinfo) - Initialize source. This is called by jpeg_read_header() before any - data is actually read. Unlike init_destination(), it may leave - bytes_in_buffer set to 0 (in which case a fill_input_buffer() call - will occur immediately). - -fill_input_buffer (j_decompress_ptr cinfo) - This is called whenever bytes_in_buffer has reached zero and more - data is wanted. In typical applications, it should read fresh data - into the buffer (ignoring the current state of next_input_byte and - bytes_in_buffer), reset the pointer & count to the start of the - buffer, and return TRUE indicating that the buffer has been reloaded. - It is not necessary to fill the buffer entirely, only to obtain at - least one more byte. bytes_in_buffer MUST be set to a positive value - if TRUE is returned. A FALSE return should only be used when I/O - suspension is desired (this mode is discussed in the next section). - -skip_input_data (j_decompress_ptr cinfo, long num_bytes) - Skip num_bytes worth of data. The buffer pointer and count should - be advanced over num_bytes input bytes, refilling the buffer as - needed. This is used to skip over a potentially large amount of - uninteresting data (such as an APPn marker). In some applications - it may be possible to optimize away the reading of the skipped data, - but it's not clear that being smart is worth much trouble; large - skips are uncommon. bytes_in_buffer may be zero on return. - A zero or negative skip count should be treated as a no-op. - -resync_to_restart (j_decompress_ptr cinfo) - This routine is called only when the decompressor has failed to find - a restart (RSTn) marker where one is expected. Its mission is to - find a suitable point for resuming decompression. For most - applications, we recommend that you just use the default resync - procedure, jpeg_resync_to_restart(). However, if you are able to back - up in the input data stream, or if you have a-priori knowledge about - the likely location of restart markers, you may be able to do better. - Read the read_restart_marker() and jpeg_resync_to_restart() routines - in jdmarker.c if you think you'd like to implement your own resync - procedure. - -term_source (j_decompress_ptr cinfo) - Terminate source --- called by jpeg_finish_decompress() after all - data has been read. Often a no-op. - -For both fill_input_buffer() and skip_input_data(), there is no such thing -as an EOF return. If the end of the file has been reached, the routine has -a choice of exiting via ERREXIT() or inserting fake data into the buffer. -In most cases, generating a warning message and inserting a fake EOI marker -is the best course of action --- this will allow the decompressor to output -however much of the image is there. In pathological cases, the decompressor -may swallow the EOI and again demand data ... just keep feeding it fake EOIs. -jdatasrc.c illustrates the recommended error recovery behavior. - -term_source() is NOT called by jpeg_abort() or jpeg_destroy(). If you want -the source manager to be cleaned up during an abort, you must do it yourself. - -You will also need code to create a jpeg_source_mgr struct, fill in its method -pointers, and insert a pointer to the struct into the "src" field of the JPEG -decompression object. This can be done in-line in your setup code if you -like, but it's probably cleaner to provide a separate routine similar to the -jpeg_stdio_src() routine of the supplied source manager. - -For more information, consult the stdio source and destination managers -in jdatasrc.c and jdatadst.c. - - -I/O suspension --------------- - -Some applications need to use the JPEG library as an incremental memory-to- -memory filter: when the compressed data buffer is filled or emptied, they want -control to return to the outer loop, rather than expecting that the buffer can -be flushed or reloaded within the data source/destination manager subroutine. -The library supports this need by providing an "I/O suspension" mode, which we -describe in this section. - -The I/O suspension mode is a limited solution: it works only in the simplest -operating modes (namely single-pass processing of single-scan JPEG files), and -it has several other restrictions which are documented below. Furthermore, -nothing is guaranteed about the maximum amount of time spent in any one call -to the library, so a single-threaded application may still have response-time -problems. If you need multi-pass processing or guaranteed response time, we -suggest you "bite the bullet" and implement a real multi-tasking capability. - -To use I/O suspension, cooperation is needed between the calling application -and the data source or destination manager; you will always need a custom -source/destination manager. (Please read the previous section if you haven't -already.) The basic idea is that the empty_output_buffer() or -fill_input_buffer() routine is a no-op, merely returning FALSE to indicate -that it has done nothing. Upon seeing this, the JPEG library suspends -operation and returns to its caller. The surrounding application is -responsible for emptying or refilling the work buffer before calling the JPEG -library again. - -Compression suspension: - -For compression suspension, use an empty_output_buffer() routine that -returns FALSE; typically it will not do anything else. This will cause the -compressor to return to the caller of jpeg_write_scanlines(), with the -return value indicating that not all the supplied scanlines have been -accepted. The application must make more room in the output buffer, adjust -the buffer pointer/count appropriately, and then call jpeg_write_scanlines() -again, pointing to the first unconsumed scanline. - -When forced to suspend, the compressor will backtrack to a convenient stopping -point (usually the start of the current MCU); it will regenerate some output -data when restarted. Therefore, although empty_output_buffer() is only called -when the buffer is filled, you should NOT dump out the entire buffer, only the -data up to the current position of next_output_byte/free_in_buffer. The data -beyond that point will be regenerated after resumption. - -Because of the backtracking behavior, a good-size output buffer is essential -for efficiency; you don't want the compressor to suspend often. (In fact, an -overly small buffer could lead to infinite looping, if a single MCU required -more data than would fit in the buffer.) We recommend a buffer of at least -several Kbytes. You may want to insert explicit code to ensure that you don't -call jpeg_write_scanlines() unless there is a reasonable amount of space in -the output buffer; in other words, flush the buffer before trying to compress -more data. - -The JPEG compressor does not support suspension while it is trying to write -JPEG markers at the beginning and end of the file. This means that - * At the beginning of a compression operation, there must be enough free - space in the output buffer to hold the header markers (typically 600 or - so bytes). The recommended buffer size is bigger than this anyway, so - this is not a problem as long as you start with an empty buffer. However, - this restriction might catch you if you insert large special markers, such - as a JFIF thumbnail image. - * When you call jpeg_finish_compress(), there must be enough space in the - output buffer to emit any buffered data and the final EOI marker. In the - current implementation, half a dozen bytes should suffice for this, but - for safety's sake we recommend ensuring that at least 100 bytes are free - before calling jpeg_finish_compress(). -Furthermore, since jpeg_finish_compress() cannot suspend, you cannot request -multi-pass operating modes such as Huffman code optimization or multiple-scan -output. That would imply that a large amount of data would be written inside -jpeg_finish_compress(), which would certainly trigger a buffer overrun. - -Decompression suspension: - -For decompression suspension, use a fill_input_buffer() routine that simply -returns FALSE (except perhaps during error recovery, as discussed below). -This will cause the decompressor to return to its caller with an indication -that suspension has occurred. This can happen at three places: - * jpeg_read_header(): will return JPEG_SUSPENDED. - * jpeg_read_scanlines(): will return the number of scanlines already - completed (possibly 0). - * jpeg_finish_decompress(): will return FALSE, rather than its usual TRUE. -The surrounding application must recognize these cases, load more data into -the input buffer, and repeat the call. In the case of jpeg_read_scanlines(), -adjust the passed pointers to reflect any scanlines successfully read. - -Just as with compression, the decompressor will typically backtrack to a -convenient restart point before suspending. The data beyond the current -position of next_input_byte/bytes_in_buffer must NOT be discarded; it will -be re-read upon resumption. In most implementations, you'll need to shift -this data down to the start of your work buffer and then load more data -after it. Again, this behavior means that a several-Kbyte work buffer is -essential for decent performance; furthermore, you should load a reasonable -amount of new data before resuming decompression. (If you loaded, say, -only one new byte each time around, you could waste a LOT of cycles.) - -The skip_input_data() source manager routine requires special care in a -suspension scenario. This routine is NOT granted the ability to suspend the -decompressor; it can decrement bytes_in_buffer to zero, but no more. If the -requested skip distance exceeds the amount of data currently in the input -buffer, then skip_input_data() must set bytes_in_buffer to zero and record the -additional skip distance somewhere else. The decompressor will immediately -call fill_input_buffer(), which will return FALSE, which will cause a -suspension return. The surrounding application must then arrange to discard -the right number of bytes before it resumes loading the input buffer. (Yes, -this design is rather baroque, but it avoids complexity in the far more common -case where a non-suspending source manager is used.) - -If the input data has been exhausted, we recommend that you emit a warning -and insert dummy EOI markers just as a non-suspending data source manager -would do. This can be handled either in the surrounding application logic or -within fill_input_buffer(); the latter is probably more efficient. If -fill_input_buffer() knows that no more data is available, it can set the -pointer/count to point to a dummy EOI marker and then return TRUE just as -though it had read more data in a non-suspending situation. - -The decompressor does not support suspension within jpeg_start_decompress(). -This means that you cannot use suspension with any multi-pass processing mode -(eg, two-pass color quantization or multiple-scan JPEG files). In single-pass -modes, jpeg_start_decompress() reads no data and thus need never suspend. - -The decompressor does not attempt to suspend within any JPEG marker; it will -backtrack to the start of the marker. Hence the input buffer must be large -enough to hold the longest marker in the file. We recommend at least a 2K -buffer. The buffer would need to be 64K to allow for arbitrary COM or APPn -markers, but the decompressor does not actually try to read these; it just -skips them by calling skip_input_data(). If you provide a special marker -handling routine that does look at such markers, coping with buffer overflow -is your problem. Ordinary JPEG markers should normally not exceed a few -hundred bytes each (DHT tables are typically the longest). For robustness -against damaged marker length counts, you may wish to insert a test in your -application for the case that the input buffer is completely full and yet the -decoder has suspended without consuming any data --- otherwise, if this -situation did occur, it would lead to an endless loop. - - -Abbreviated datastreams and multiple images -------------------------------------------- - -A JPEG compression or decompression object can be reused to process multiple -images. This saves a small amount of time per image by eliminating the -"create" and "destroy" operations, but that isn't the real purpose of the -feature. Rather, reuse of an object provides support for abbreviated JPEG -datastreams. Object reuse can also simplify processing a series of images in -a single input or output file. This section explains these features. - -A JPEG file normally contains several hundred bytes worth of quantization -and Huffman tables. In a situation where many images will be stored or -transmitted with identical tables, this may represent an annoying overhead. -The JPEG standard therefore permits tables to be omitted. The standard -defines three classes of JPEG datastreams: - * "Interchange" datastreams contain an image and all tables needed to decode - the image. These are the usual kind of JPEG file. - * "Abbreviated image" datastreams contain an image, but are missing some or - all of the tables needed to decode that image. - * "Abbreviated table specification" (henceforth "tables-only") datastreams - contain only table specifications. -To decode an abbreviated image, it is necessary to load the missing table(s) -into the decoder beforehand. This can be accomplished by reading a separate -tables-only file. A variant scheme uses a series of images in which the first -image is an interchange (complete) datastream, while subsequent ones are -abbreviated and rely on the tables loaded by the first image. It is assumed -that once the decoder has read a table, it will remember that table until a -new definition for the same table number is encountered. - -It is the application designer's responsibility to figure out how to associate -the correct tables with an abbreviated image. While abbreviated datastreams -can be useful in a closed environment, their use is strongly discouraged in -any situation where data exchange with other applications might be needed. -Caveat designer. - -The JPEG library provides support for reading and writing any combination of -tables-only datastreams and abbreviated images. In both compression and -decompression objects, a quantization or Huffman table will be retained for -the lifetime of the object, unless it is overwritten by a new table definition. - - -To create abbreviated image datastreams, it is only necessary to tell the -compressor not to emit some or all of the tables it is using. Each -quantization and Huffman table struct contains a boolean field "sent_table", -which normally is initialized to FALSE. For each table used by the image, the -header-writing process emits the table and sets sent_table = TRUE unless it is -already TRUE. (In normal usage, this prevents outputting the same table -definition multiple times, as would otherwise occur because the chroma -components typically share tables.) Thus, setting this field to TRUE before -calling jpeg_start_compress() will prevent the table from being written at -all. - -If you want to create a "pure" abbreviated image file containing no tables, -just call "jpeg_suppress_tables(&cinfo, TRUE)" after constructing all the -tables. If you want to emit some but not all tables, you'll need to set the -individual sent_table fields directly. - -To create an abbreviated image, you must also call jpeg_start_compress() -with a second parameter of FALSE, not TRUE. Otherwise jpeg_start_compress() -will force all the sent_table fields to FALSE. (This is a safety feature to -prevent abbreviated images from being created accidentally.) - -To create a tables-only file, perform the same parameter setup that you -normally would, but instead of calling jpeg_start_compress() and so on, call -jpeg_write_tables(&cinfo). This will write an abbreviated datastream -containing only SOI, DQT and/or DHT markers, and EOI. All the quantization -and Huffman tables that are currently defined in the compression object will -be emitted unless their sent_tables flag is already TRUE, and then all the -sent_tables flags will be set TRUE. - -A sure-fire way to create matching tables-only and abbreviated image files -is to proceed as follows: - - create JPEG compression object - set JPEG parameters - set destination to tables-only file - jpeg_write_tables(&cinfo); - set destination to image file - jpeg_start_compress(&cinfo, FALSE); - write data... - jpeg_finish_compress(&cinfo); - -Since the JPEG parameters are not altered between writing the table file and -the abbreviated image file, the same tables are sure to be used. Of course, -you can repeat the jpeg_start_compress() ... jpeg_finish_compress() sequence -many times to produce many abbreviated image files matching the table file. - -You cannot suppress output of the computed Huffman tables when Huffman -optimization is selected. (If you could, there'd be no way to decode the -image...) Generally, you don't want to set optimize_coding = TRUE when -you are trying to produce abbreviated files. - -In some cases you might want to compress an image using tables which are -not stored in the application, but are defined in an interchange or -tables-only file readable by the application. This can be done by setting up -a JPEG decompression object to read the specification file, then copying the -tables into your compression object. - - -To read abbreviated image files, you simply need to load the proper tables -into the decompression object before trying to read the abbreviated image. -If the proper tables are stored in the application program, you can just -allocate the table structs and fill in their contents directly. More commonly -you'd want to read the tables from a tables-only file. The jpeg_read_header() -call is sufficient to read a tables-only file. You must pass a second -parameter of FALSE to indicate that you do not require an image to be present. -Thus, the typical scenario is - - create JPEG decompression object - set source to tables-only file - jpeg_read_header(&cinfo, FALSE); - set source to abbreviated image file - jpeg_read_header(&cinfo, TRUE); - set decompression parameters - jpeg_start_decompress(&cinfo); - read data... - jpeg_finish_decompress(&cinfo); - -In some cases, you may want to read a file without knowing whether it contains -an image or just tables. In that case, pass FALSE and check the return value -from jpeg_read_header(): it will be JPEG_HEADER_OK if an image was found, -JPEG_HEADER_TABLES_ONLY if only tables were found. (A third return value, -JPEG_SUSPENDED, is possible when using a suspending data source manager.) -Note that jpeg_read_header() will not complain if you read an abbreviated -image for which you haven't loaded the missing tables; the missing-table check -occurs in jpeg_start_decompress(). - - -It is possible to read a series of images from a single source file by -repeating the jpeg_read_header() ... jpeg_finish_decompress() sequence, -without releasing/recreating the JPEG object or the data source module. -(If you did reinitialize, any partial bufferload left in the data source -buffer at the end of one image would be discarded, causing you to lose the -start of the next image.) When you use this method, stored tables are -automatically carried forward, so some of the images can be abbreviated images -that depend on tables from earlier images. - -If you intend to write a series of images into a single destination file, -you might want to make a specialized data destination module that doesn't -flush the output buffer at term_destination() time. This would speed things -up by some trifling amount. Of course, you'd need to remember to flush the -buffer after the last image. You can make the later images be abbreviated -ones by passing FALSE to jpeg_start_compress(). - - -Special markers ---------------- - -Some applications may need to insert or extract special data in the JPEG -datastream. The JPEG standard provides marker types "COM" (comment) and -"APP0" through "APP15" (application) to hold application-specific data. -Unfortunately, the use of these markers is not specified by the standard. -COM markers are fairly widely used to hold user-supplied text. The JFIF file -format spec uses APP0 markers with specified initial strings to hold certain -data. Adobe applications use APP14 markers beginning with the string "Adobe" -for miscellaneous data. Other APPn markers are rarely seen, but might -contain almost anything. - -If you wish to store user-supplied text, we recommend you use COM markers -and place readable 7-bit ASCII text in them. Newline conventions are not -standardized --- expect to find LF (Unix style), CR/LF (DOS style), or CR -(Mac style). A robust COM reader should be able to cope with random binary -garbage, including nulls, since some applications generate COM markers -containing non-ASCII junk. (But yours should not be one of them.) - -For program-supplied data, use an APPn marker, and be sure to begin it with an -identifying string so that you can tell whether the marker is actually yours. -It's probably best to avoid using APP0 or APP14 for any private markers. - -Keep in mind that at most 65533 bytes can be put into one marker, but you -can have as many markers as you like. - -By default, the JPEG compression library will write a JFIF APP0 marker if the -selected JPEG colorspace is grayscale or YCbCr, or an Adobe APP14 marker if -the selected colorspace is RGB, CMYK, or YCCK. You can disable this, but -we don't recommend it. The decompression library will recognize JFIF and -Adobe markers and will set the JPEG colorspace properly when one is found. - -You can write special markers immediately following the datastream header by -calling jpeg_write_marker() after jpeg_start_compress() and before the first -call to jpeg_write_scanlines(). When you do this, the markers appear after -the SOI and the JFIF APP0 and Adobe APP14 markers (if written), but before -all else. Write the marker type parameter as "JPEG_COM" for COM or -"JPEG_APP0 + n" for APPn. (Actually, jpeg_write_marker will let you write -any marker type, but we don't recommend writing any other kinds of marker.) -For example, to write a user comment string pointed to by comment_text: - jpeg_write_marker(cinfo, JPEG_COM, comment_text, strlen(comment_text)); -Or if you prefer to synthesize the marker byte sequence yourself, you can -just cram it straight into the data destination module. - -For decompression, you can supply your own routine to process COM or APPn -markers by calling jpeg_set_marker_processor(). Usually you'd call this -after creating a decompression object and before calling jpeg_read_header(), -because the markers of interest will normally be scanned by jpeg_read_header. -Once you've supplied a routine, it will be used for the life of that -decompression object. A separate routine may be registered for COM and for -each APPn marker code. - -A marker processor routine must have the signature - boolean jpeg_marker_parser_method (j_decompress_ptr cinfo) -Although the marker code is not explicitly passed, the routine can find it -in cinfo->unread_marker. At the time of call, the marker proper has been -read from the data source module. The processor routine is responsible for -reading the marker length word and the remaining parameter bytes, if any. -Return TRUE to indicate success. (FALSE should be returned only if you are -using a suspending data source and it tells you to suspend. See the standard -marker processors in jdmarker.c for appropriate coding methods if you need to -use a suspending data source.) - -If you override the default APP0 or APP14 processors, it is up to you to -recognize JFIF and Adobe markers if you want colorspace recognition to occur -properly. We recommend copying and extending the default processors if you -want to do that. - -A simple example of an external COM processor can be found in djpeg.c. - - -Raw (downsampled) image data ----------------------------- - -Some applications need to supply already-downsampled image data to the JPEG -compressor, or to receive raw downsampled data from the decompressor. The -library supports this requirement by allowing the application to write or -read raw data, bypassing the normal preprocessing or postprocessing steps. -The interface is different from the standard one and is somewhat harder to -use. If your interest is merely in bypassing color conversion, we recommend -that you use the standard interface and simply set jpeg_color_space = -in_color_space (or jpeg_color_space = out_color_space for decompression). -The mechanism described in this section is necessary only to supply or -receive downsampled image data, in which not all components have the same -dimensions. - - -To compress raw data, you must supply the data in the colorspace to be used -in the JPEG file (please read the earlier section on Special color spaces) -and downsampled to the sampling factors specified in the JPEG parameters. -You must supply the data in the format used internally by the JPEG library, -namely a JSAMPIMAGE array. This is an array of pointers to two-dimensional -arrays, each of type JSAMPARRAY. Each 2-D array holds the values for one -color component. This structure is necessary since the components are of -different sizes. If the image dimensions are not a multiple of the MCU size, -you must also pad the data correctly (usually, this is done by replicating -the last column and/or row). The data must be padded to a multiple of a DCT -block in each component: that is, each downsampled row must contain a -multiple of 8 valid samples, and there must be a multiple of 8 sample rows -for each component. (For applications such as conversion of digital TV -images, the standard image size is usually a multiple of the DCT block size, -so that no padding need actually be done.) - -The procedure for compression of raw data is basically the same as normal -compression, except that you call jpeg_write_raw_data() in place of -jpeg_write_scanlines(). Before calling jpeg_start_compress(), you must do -the following: - * Set cinfo->raw_data_in to TRUE. (It is set FALSE by jpeg_set_defaults().) - This notifies the library that you will be supplying raw data. - * Ensure jpeg_color_space is correct --- an explicit jpeg_set_colorspace() - call is a good idea. Note that since color conversion is bypassed, - in_color_space is ignored, except that jpeg_set_defaults() uses it to - choose the default jpeg_color_space setting. - * Ensure the sampling factors, cinfo->comp_info[i].h_samp_factor and - cinfo->comp_info[i].v_samp_factor, are correct. Since these indicate the - dimensions of the data you are supplying, it's wise to set them - explicitly, rather than assuming the library's defaults are what you want. - -To pass raw data to the library, call jpeg_write_raw_data() in place of -jpeg_write_scanlines(). The two routines work similarly except that -jpeg_write_raw_data takes a JSAMPIMAGE data array rather than JSAMPARRAY. -The scanlines count passed to and returned from jpeg_write_raw_data is -measured in terms of the component with the largest v_samp_factor. - -jpeg_write_raw_data() processes one MCU row per call, which is to say -v_samp_factor*DCTSIZE sample rows of each component. The passed num_lines -value must be at least max_v_samp_factor*DCTSIZE, and the return value will -be exactly that amount (or possibly some multiple of that amount, in future -library versions). This is true even on the last call at the bottom of the -image; don't forget to pad your data as necessary. - -The required dimensions of the supplied data can be computed for each -component as - cinfo->comp_info[i].width_in_blocks*DCTSIZE samples per row - cinfo->comp_info[i].height_in_blocks*DCTSIZE rows in image -after jpeg_start_compress() has initialized those fields. If the valid data -is smaller than this, it must be padded appropriately. For some sampling -factors and image sizes, additional dummy DCT blocks are inserted to make -the image a multiple of the MCU dimensions. The library creates such dummy -blocks itself; it does not read them from your supplied data. Therefore you -need never pad by more than DCTSIZE samples. An example may help here. -Assume 2h2v downsampling of YCbCr data, that is - cinfo->comp_info[0].h_samp_factor = 2 for Y - cinfo->comp_info[0].v_samp_factor = 2 - cinfo->comp_info[1].h_samp_factor = 1 for Cb - cinfo->comp_info[1].v_samp_factor = 1 - cinfo->comp_info[2].h_samp_factor = 1 for Cr - cinfo->comp_info[2].v_samp_factor = 1 -and suppose that the nominal image dimensions (cinfo->image_width and -cinfo->image_height) are 101x101 pixels. Then jpeg_start_compress() will -compute downsampled_width = 101 and width_in_blocks = 13 for Y, -downsampled_width = 51 and width_in_blocks = 7 for Cb and Cr (and the same -for the height fields). You must pad the Y data to at least 13*8 = 104 -columns and rows, the Cb/Cr data to at least 7*8 = 56 columns and rows. The -MCU height is max_v_samp_factor = 2 DCT rows so you must pass at least 16 -scanlines on each call to jpeg_write_raw_data(), which is to say 16 actual -sample rows of Y and 8 each of Cb and Cr. A total of 7 MCU rows are needed, -so you must pass a total of 7*16 = 112 "scanlines". The last DCT block row -of Y data is dummy, so it doesn't matter what you pass for it in the data -arrays, but the scanlines count must total up to 112 so that all of the Cb -and Cr data gets passed. - -Currently, output suspension is not supported with raw data output: an error -will result if the data destination module tries to suspend. - - -Decompression with raw data output implies bypassing all postprocessing: -you cannot ask for color quantization, for instance. More seriously, you must -deal with the color space and sampling factors present in the incoming file. -If your application only handles, say, 2h1v YCbCr data, you must check for -and fail on other color spaces or other sampling factors. - -To obtain raw data output, set cinfo->raw_data_out = TRUE before -jpeg_start_decompress() (it is set FALSE by jpeg_read_header()). Be sure to -verify that the color space and sampling factors are ones you can handle. -Then call jpeg_read_raw_data() in place of jpeg_read_scanlines(). The -decompression process is otherwise the same as usual. - -jpeg_read_raw_data() returns one MCU row per call, and thus you must pass a -buffer of at least max_v_samp_factor*DCTSIZE scanlines (scanline counting is -the same as for raw-data compression). The buffer you pass must be large -enough to hold the actual data plus padding to DCT-block boundaries. As with -compression, any entirely dummy DCT blocks are not processed so you need not -allocate space for them, but the total scanline count includes them. The -above example of computing buffer dimensions for raw-data compression is -equally valid for decompression. - -Input suspension is supported with raw-data decompression: if the data source -module suspends, jpeg_read_raw_data() will return 0. - - -Progress monitoring -------------------- - -Some applications may need to regain control from the JPEG library every so -often. The typical use of this feature is to produce a percent-done bar or -other progress display. (For a simple example, see cjpeg.c or djpeg.c.) -Although you do get control back frequently during the data-transferring pass -(the jpeg_read_scanlines or jpeg_write_scanlines loop), any additional passes -will occur inside jpeg_finish_compress or jpeg_start_decompress; those -routines may take a long time to execute, and you don't get control back -until they are done. - -You can define a progress-monitor routine which will be called periodically -by the library. No guarantees are made about how often this call will occur, -so we don't recommend you use it for mouse tracking or anything like that. -At present, a call will occur once per MCU row, scanline, or sample row -group, whichever unit is convenient for the current processing mode; so the -wider the image, the longer the time between calls. (During the data -transferring pass, only one call occurs per call of jpeg_read_scanlines or -jpeg_write_scanlines, so don't pass a large number of scanlines at once if -you want fine resolution in the progress count.) - -To establish a progress-monitor callback, create a struct jpeg_progress_mgr, -fill in its progress_monitor field with a pointer to your callback routine, -and set cinfo->progress to point to the struct. The callback will be called -whenever cinfo->progress is non-NULL. (This pointer is set to NULL by -jpeg_create_compress or jpeg_create_decompress; the library will not change -it thereafter. So if you allocate dynamic storage for the progress struct, -make sure it will live as long as the JPEG object does. Allocating from the -JPEG memory manager with lifetime JPOOL_PERMANENT will work nicely.) You -can use the same callback routine for both compression and decompression. - -The jpeg_progress_mgr struct contains four fields which are set by the library: - long pass_counter; /* work units completed in this pass */ - long pass_limit; /* total number of work units in this pass */ - int completed_passes; /* passes completed so far */ - int total_passes; /* total number of passes expected */ -During any one pass, pass_counter increases from 0 up to (not including) -pass_limit; the step size is not necessarily 1. Both the step size and the -limit may differ from one pass to another. The expected total number of -passes is in total_passes, and the number of passes already completed is in -completed_passes. Thus the fraction of work completed may be estimated as - completed_passes + (pass_counter/pass_limit) - -------------------------------------------- - total_passes -ignoring the fact that the passes may not be equal amounts of work. - -When decompressing, the total_passes value is not trustworthy, because it -depends on the number of scans in the JPEG file, which isn't always known in -advance. In the current implementation, completed_passes may jump by more -than one when dealing with a multiple-scan input file. About all that is -really safe to assume is that when completed_passes = total_passes - 1, the -current pass will be the last one. - -If you really need to use the callback mechanism for time-critical tasks -like mouse tracking, you could insert additional calls inside some of the -library's inner loops. - - -Memory management ------------------ - -This section covers some key facts about the JPEG library's built-in memory -manager. For more info, please read structure.doc's section about the memory -manager, and consult the source code if necessary. - -All memory and temporary file allocation within the library is done via the -memory manager. If necessary, you can replace the "back end" of the memory -manager to control allocation yourself (for example, if you don't want the -library to use malloc() and free() for some reason). - -Some data is allocated "permanently" and will not be freed until the JPEG -object is destroyed. Most data is allocated "per image" and is freed by -jpeg_finish_compress, jpeg_finish_decompress, or jpeg_abort. You can call the -memory manager yourself to allocate structures that will automatically be -freed at these times. Typical code for this is - ptr = (*cinfo->mem->alloc_small) ((j_common_ptr) cinfo, JPOOL_IMAGE, size); -Use JPOOL_PERMANENT to get storage that lasts as long as the JPEG object. -Use alloc_large instead of alloc_small for anything bigger than a few Kbytes. -There are also alloc_sarray and alloc_barray routines that automatically -build 2-D sample or block arrays. - -The library's minimum space requirements to process an image depend on the -image's width, but not on its height, because the library ordinarily works -with "strip" buffers that are as wide as the image but just a few rows high. -Some operating modes (eg, two-pass color quantization) require full-image -buffers. Such buffers are treated as "virtual arrays": only the current strip -need be in memory, and the rest can be swapped out to a temporary file. - -If you use the simplest memory manager back end (jmemnobs.c), then no -temporary files are used; virtual arrays are simply malloc()'d. Images bigger -than memory can be processed only if your system supports virtual memory. -The other memory manager back ends support temporary files of various flavors -and thus work in machines without virtual memory. They may also be useful on -Unix machines if you need to process images that exceed available swap space. - -When using temporary files, the library will make the in-memory buffers for -its virtual arrays just big enough to stay within a "maximum memory" setting. -Your application can set this limit by setting cinfo->mem->max_memory_to_use -after creating the JPEG object. (Of course, there is still a minimum size for -the buffers, so the max-memory setting is effective only if it is bigger than -the minimum space needed.) If you allocate any large structures yourself, you -must allocate them before jpeg_start_compress() or jpeg_start_decompress() in -order to have them counted against the max memory limit. Also keep in mind -that space allocated with alloc_small() is ignored, on the assumption that -it's too small to be worth worrying about. - -If you use the jmemname.c or jmemdos.c memory manager back end, it is -important to clean up the JPEG object properly to ensure that the temporary -files get deleted. (This is especially crucial with jmemdos.c, where the -"temporary files" may be extended-memory segments; if they are not freed, -DOS will require a reboot to recover the memory.) Thus, with these memory -managers, it's a good idea to provide a signal handler that will trap any -early exit from your program. The handler should call either jpeg_abort() -or jpeg_destroy() for any active JPEG objects. A handler is not needed with -jmemnobs.c, and shouldn't be necessary with jmemansi.c either, since the C -library is supposed to take care of deleting files made with tmpfile(). - - -Library compile-time options ----------------------------- - -A number of compile-time options are available by modifying jmorecfg.h. - -The JPEG standard provides for both the baseline 8-bit DCT process and -a 12-bit DCT process. 12-bit lossy JPEG is supported if you define -BITS_IN_JSAMPLE as 12 rather than 8. Note that this causes JSAMPLE to be -larger than a char, so it affects the surrounding application's image data. -At present, a 12-bit library can handle *only* 12-bit images, not both -precisions. (If you need to include both 8- and 12-bit libraries in a -single application, you could probably do it by defining -NEED_SHORT_EXTERNAL_NAMES for just one of the copies. You'd have to access -the 8-bit and 12-bit copies from separate application source files. This is -untested ... if you try it, we'd like to hear whether it works!) - -The maximum number of components (color channels) in the image is determined -by MAX_COMPONENTS. The JPEG standard allows up to 255 components, but we -expect that few applications will need more than four or so. - -On machines with unusual data type sizes, you may be able to improve -performance or reduce memory space by tweaking the various typedefs in -jmorecfg.h. In particular, on some RISC CPUs, access to arrays of "short"s -is quite slow; consider trading memory for speed by making JCOEF, INT16, and -UINT16 be "int" or "unsigned int". UINT8 is also a candidate to become int. -You probably don't want to make JSAMPLE be int unless you have lots of memory -to burn. - -You can reduce the size of the library by compiling out various optional -functions. To do this, undefine xxx_SUPPORTED symbols as necessary. - - -Portability considerations --------------------------- - -The JPEG library has been written to be extremely portable; the sample -applications cjpeg and djpeg are slightly less so. This section summarizes -the design goals in this area. (If you encounter any bugs that cause the -library to be less portable than is claimed here, we'd appreciate hearing -about them.) - -The code works fine on both ANSI and pre-ANSI C compilers, using any of the -popular system include file setups, and some not-so-popular ones too. See -install.doc for configuration procedures. - -The code is not dependent on the exact sizes of the C data types. As -distributed, we make the assumptions that - char is at least 8 bits wide - short is at least 16 bits wide - int is at least 16 bits wide - long is at least 32 bits wide -(These are the minimum requirements of the ANSI C standard.) Wider types will -work fine, although memory may be used inefficiently if char is much larger -than 8 bits or short is much bigger than 16 bits. The code should work -equally well with 16- or 32-bit ints. - -In a system where these assumptions are not met, you may be able to make the -code work by modifying the typedefs in jmorecfg.h. However, you will probably -have difficulty if int is less than 16 bits wide, since references to plain -int abound in the code. - -char can be either signed or unsigned, although the code runs faster if an -unsigned char type is available. If char is wider than 8 bits, you will need -to redefine JOCTET and/or provide custom data source/destination managers so -that JOCTET represents exactly 8 bits of data on external storage. - -The JPEG library proper does not assume ASCII representation of characters. -But some of the image file I/O modules in cjpeg/djpeg do have ASCII -dependencies in file-header manipulation; so does cjpeg's select_file_type() -routine. - -The JPEG library does not rely heavily on the C library. In particular, C -stdio is used only by the data source/destination modules and the error -handler, all of which are application-replaceable. (cjpeg/djpeg are more -heavily dependent on stdio.) malloc and free are called only from the memory -manager "back end" module, so you can use a different memory allocator by -replacing that one file. - -The code generally assumes that C names must be unique in the first 15 -characters. However, global function names can be made unique in the -first 6 characters by defining NEED_SHORT_EXTERNAL_NAMES. - -More info about porting the code may be gleaned by reading jconfig.doc, -jmorecfg.h, and jinclude.h. - - -Notes for MS-DOS implementors ------------------------------ - -The IJG code is designed to work efficiently in 80x86 "small" or "medium" -memory models (i.e., data pointers are 16 bits unless explicitly declared -"far"; code pointers can be either size). You may be able to use small -model to compile cjpeg or djpeg by itself, but you will probably have to use -medium model for any larger application. This won't make much difference in -performance. You *will* take a noticeable performance hit if you use a -large-data memory model (perhaps 10%-25%), and you should avoid "huge" model -if at all possible. - -The JPEG library typically needs 2Kb-3Kb of stack space. It will also -malloc about 20K-30K of near heap space while executing (and lots of far -heap, but that doesn't count in this calculation). This figure will vary -depending on selected operating mode, and to a lesser extent on image size. -Thus you have perhaps 25K available for static data and other modules' near -heap space before you need to go to a larger memory model. The C library's -static data will account for several K of this, but that still leaves a good -deal for your needs. (If you are tight on space, you could reduce the sizes -of the I/O buffers allocated by jdatasrc.c and jdatadst.c, say from 4K to -1K.) - -About 2K of the near heap space is "permanent" memory that will not be -released until you destroy the JPEG object. This is only an issue if you -save a JPEG object between compression or decompression operations. - -Far data space may also be a tight resource when you are dealing with large -images. The most memory-intensive case is decompression with two-pass color -quantization, or single-pass quantization to an externally supplied color -map. This requires a 128Kb color lookup table plus strip buffers amounting -to about 50 bytes per column for typical sampling ratios (eg, about 32000 -bytes for a 640-pixel-wide image). You may not be able to process wide -images if you have large data structures of your own. - -Of course, all of these concerns vanish if you use a 32-bit flat-memory-model -compiler, such as DJGPP or Watcom C. We highly recommend flat model if you -can use it; the JPEG library is significantly faster in flat model.