136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneUSING THE IJG JPEG LIBRARY 236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 3a73e870ad02de20c2b34cb3a5382c2846c2afbe3DRCThis file was part of the Independent JPEG Group's software: 46eb7d3798b5a79347c62825fc4c16f7ce673bdd0Alex NaidisCopyright (C) 1994-2013, Thomas G. Lane, Guido Vollbeding. 5da13af6b8d5427af89bbdc5698b4e09d0ea814feDRClibjpeg-turbo Modifications: 60ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCCopyright (C) 2010, 2014-2016, D. R. Commander. 7ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCCopyright (C) 2015, Google, Inc. 86eb7d3798b5a79347c62825fc4c16f7ce673bdd0Alex NaidisFor conditions of distribution and use, see the accompanying README.ijg file. 936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 1036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 1136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThis file describes how to use the IJG JPEG library within an application 1236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneprogram. Read it if you want to write a program that uses the library. 1336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 1436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe file example.c provides heavily commented skeleton code for calling the 1536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJPEG library. Also see jpeglib.h (the include file to be used by application 1636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneprograms) for full details about data structures and function parameter lists. 1736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe library source code, of course, is the ultimate reference. 1836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 1936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneNote that there have been *major* changes from the application interface 2036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanepresented by IJG version 4 and earlier versions. The old design had several 2136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneinherent limitations, and it had accumulated a lot of cruft as we added 2236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefeatures while trying to minimize application-interface changes. We have 2336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesacrificed backward compatibility in the version 5 rewrite, but we think the 2436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneimprovements justify this. 2536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 2636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 2736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTABLE OF CONTENTS 2836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane----------------- 2936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 3036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneOverview: 31b775351012af176720429ac21d11682a0b75b4b7DRC Functions provided by the library 32b775351012af176720429ac21d11682a0b75b4b7DRC Outline of typical usage 3336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneBasic library usage: 34b775351012af176720429ac21d11682a0b75b4b7DRC Data formats 35b775351012af176720429ac21d11682a0b75b4b7DRC Compression details 36b775351012af176720429ac21d11682a0b75b4b7DRC Decompression details 37b775351012af176720429ac21d11682a0b75b4b7DRC Mechanics of usage: include files, linking, etc 3836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAdvanced features: 39b775351012af176720429ac21d11682a0b75b4b7DRC Compression parameter selection 40b775351012af176720429ac21d11682a0b75b4b7DRC Decompression parameter selection 41b775351012af176720429ac21d11682a0b75b4b7DRC Special color spaces 42b775351012af176720429ac21d11682a0b75b4b7DRC Error handling 43b775351012af176720429ac21d11682a0b75b4b7DRC Compressed data handling (source and destination managers) 44b775351012af176720429ac21d11682a0b75b4b7DRC I/O suspension 45b775351012af176720429ac21d11682a0b75b4b7DRC Progressive JPEG support 46b775351012af176720429ac21d11682a0b75b4b7DRC Buffered-image mode 47b775351012af176720429ac21d11682a0b75b4b7DRC Abbreviated datastreams and multiple images 48b775351012af176720429ac21d11682a0b75b4b7DRC Special markers 49b775351012af176720429ac21d11682a0b75b4b7DRC Raw (downsampled) image data 50b775351012af176720429ac21d11682a0b75b4b7DRC Really raw data: DCT coefficients 51b775351012af176720429ac21d11682a0b75b4b7DRC Progress monitoring 52b775351012af176720429ac21d11682a0b75b4b7DRC Memory management 53b775351012af176720429ac21d11682a0b75b4b7DRC Memory usage 54b775351012af176720429ac21d11682a0b75b4b7DRC Library compile-time options 55b775351012af176720429ac21d11682a0b75b4b7DRC Portability considerations 5636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 5736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou should read at least the overview and basic usage sections before trying 5836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneto program with the library. The sections on advanced features can be read 5936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneif and when you need them. 6036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 6136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 6236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneOVERVIEW 6336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane======== 6436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 6536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneFunctions provided by the library 6636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane--------------------------------- 6736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 6836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe IJG JPEG library provides C code to read and write JPEG-compressed image 6936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefiles. The surrounding application program receives or supplies image data a 7036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanescanline at a time, using a straightforward uncompressed image format. All 7136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedetails of color conversion and other preprocessing/postprocessing can be 7236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanehandled by the library. 7336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 7436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe library includes a substantial amount of code that is not covered by the 7536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJPEG standard but is necessary for typical applications of JPEG. These 7636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefunctions preprocess the image before JPEG compression or postprocess it after 7736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedecompression. They include colorspace conversion, downsampling/upsampling, 7836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneand color quantization. The application indirectly selects use of this code 7936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneby specifying the format in which it wishes to supply or receive image data. 8036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneFor example, if colormapped output is requested, then the decompression 8136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanelibrary automatically invokes color quantization. 8236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 8336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneA wide range of quality vs. speed tradeoffs are possible in JPEG processing, 8436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneand even more so in decompression postprocessing. The decompression library 8536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneprovides multiple implementations that cover most of the useful tradeoffs, 8636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneranging from very-high-quality down to fast-preview operation. On the 8736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecompression side we have generally not provided low-quality choices, since 8836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecompression is normally less time-critical. It should be understood that the 8936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanelow-quality modes may not meet the JPEG standard's accuracy requirements; 9036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanenonetheless, they are useful for viewers. 9136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 9236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneA word about functions *not* provided by the library. We handle a subset of 93bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe ISO JPEG standard; most baseline, extended-sequential, and progressive 94bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneJPEG processes are supported. (Our subset includes all features now in common 95bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneuse.) Unsupported ISO options include: 96b775351012af176720429ac21d11682a0b75b4b7DRC * Hierarchical storage 97b775351012af176720429ac21d11682a0b75b4b7DRC * Lossless JPEG 98b775351012af176720429ac21d11682a0b75b4b7DRC * DNL marker 99b775351012af176720429ac21d11682a0b75b4b7DRC * Nonintegral subsampling ratios 10036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneWe support both 8- and 12-bit data precision, but this is a compile-time 10136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanechoice rather than a run-time choice; hence it is difficult to use both 10236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneprecisions in a single application. 10336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 10436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneBy itself, the library handles only interchange JPEG datastreams --- in 10536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneparticular the widely used JFIF file format. The library can be used by 10636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesurrounding code to process interchange or abbreviated JPEG datastreams that 107bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneare embedded in more complex file formats. (For example, this library is 108bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneused by the free LIBTIFF library to support JPEG compression in TIFF.) 10936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 11036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 11136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneOutline of typical usage 11236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane------------------------ 11336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 11436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe rough outline of a JPEG compression operation is: 11536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 116b775351012af176720429ac21d11682a0b75b4b7DRC Allocate and initialize a JPEG compression object 117b775351012af176720429ac21d11682a0b75b4b7DRC Specify the destination for the compressed data (eg, a file) 118b775351012af176720429ac21d11682a0b75b4b7DRC Set parameters for compression, including image size & colorspace 119b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_start_compress(...); 120b775351012af176720429ac21d11682a0b75b4b7DRC while (scan lines remain to be written) 121b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_write_scanlines(...); 122b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_finish_compress(...); 123b775351012af176720429ac21d11682a0b75b4b7DRC Release the JPEG compression object 12436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 12536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneA JPEG compression object holds parameters and working state for the JPEG 12636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanelibrary. We make creation/destruction of the object separate from starting 12736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneor finishing compression of an image; the same object can be re-used for a 12836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneseries of image compression operations. This makes it easy to re-use the 12936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesame parameter settings for a sequence of images. Re-use of a JPEG object 13036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanealso has important implications for processing abbreviated JPEG datastreams, 13136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneas discussed later. 13236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 13336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe image data to be compressed is supplied to jpeg_write_scanlines() from 13436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanein-memory buffers. If the application is doing file-to-file compression, 13536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanereading image data from the source file is the application's responsibility. 13636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe library emits compressed data by calling a "data destination manager", 13736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewhich typically will write the data into a file; but the application can 13836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneprovide its own destination manager to do something else. 13936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 14036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneSimilarly, the rough outline of a JPEG decompression operation is: 14136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 142b775351012af176720429ac21d11682a0b75b4b7DRC Allocate and initialize a JPEG decompression object 143b775351012af176720429ac21d11682a0b75b4b7DRC Specify the source of the compressed data (eg, a file) 144b775351012af176720429ac21d11682a0b75b4b7DRC Call jpeg_read_header() to obtain image info 145b775351012af176720429ac21d11682a0b75b4b7DRC Set parameters for decompression 146b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_start_decompress(...); 147b775351012af176720429ac21d11682a0b75b4b7DRC while (scan lines remain to be read) 148b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_read_scanlines(...); 149b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_finish_decompress(...); 150b775351012af176720429ac21d11682a0b75b4b7DRC Release the JPEG decompression object 15136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 15236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThis is comparable to the compression outline except that reading the 15336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedatastream header is a separate step. This is helpful because information 15436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneabout the image's size, colorspace, etc is available when the application 15536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneselects decompression parameters. For example, the application can choose an 15636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneoutput scaling ratio that will fit the image into the available screen size. 15736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 15836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe decompression library obtains compressed data by calling a data source 15936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemanager, which typically will read the data from a file; but other behaviors 16036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecan be obtained with a custom source manager. Decompressed data is delivered 16136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneinto in-memory buffers passed to jpeg_read_scanlines(). 16236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 16336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIt is possible to abort an incomplete compression or decompression operation 16436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneby calling jpeg_abort(); or, if you do not need to retain the JPEG object, 16536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesimply release it by calling jpeg_destroy(). 16636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 16736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJPEG compression and decompression objects are two separate struct types. 16836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneHowever, they share some common fields, and certain routines such as 16936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_destroy() can work on either type of object. 17036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 17136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe JPEG library has no static variables: all state is in the compression 17236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneor decompression object. Therefore it is possible to process multiple 17336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecompression and decompression operations concurrently, using multiple JPEG 17436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneobjects. 17536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 17636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneBoth compression and decompression can be done in an incremental memory-to- 177bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanememory fashion, if suitable source/destination managers are used. See the 178bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanesection on "I/O suspension" for more details. 17936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 18036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 18136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneBASIC LIBRARY USAGE 18236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane=================== 18336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 18436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneData formats 18536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane------------ 18636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 18736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneBefore diving into procedural details, it is helpful to understand the 18836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneimage data format that the JPEG library expects or returns. 18936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 19036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe standard input image format is a rectangular array of pixels, with each 191489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanepixel having the same number of "component" or "sample" values (color 192489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanechannels). You must specify how many components there are and the colorspace 193489583f5165e05d37302e8eeec58104ea0109127Thomas G. Laneinterpretation of the components. Most applications will use RGB data 194489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lane(three components per pixel) or grayscale data (one component per pixel). 195489583f5165e05d37302e8eeec58104ea0109127Thomas G. LanePLEASE NOTE THAT RGB DATA IS THREE SAMPLES PER PIXEL, GRAYSCALE ONLY ONE. 196489583f5165e05d37302e8eeec58104ea0109127Thomas G. LaneA remarkable number of people manage to miss this, only to find that their 197489583f5165e05d37302e8eeec58104ea0109127Thomas G. Laneprograms don't work with grayscale JPEG files. 198489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lane 199489583f5165e05d37302e8eeec58104ea0109127Thomas G. LaneThere is no provision for colormapped input. JPEG files are always full-color 200489583f5165e05d37302e8eeec58104ea0109127Thomas G. Laneor full grayscale (or sometimes another colorspace such as CMYK). You can 201489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanefeed in a colormapped image by expanding it to full-color format. However 202489583f5165e05d37302e8eeec58104ea0109127Thomas G. LaneJPEG often doesn't work very well with source data that has been colormapped, 203489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanebecause of dithering noise. This is discussed in more detail in the JPEG FAQ 2046eb7d3798b5a79347c62825fc4c16f7ce673bdd0Alex Naidisand the other references mentioned in the README.ijg file. 20536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 20636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LanePixels are stored by scanlines, with each scanline running from left to 20736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneright. The component values for each pixel are adjacent in the row; for 20836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneexample, R,G,B,R,G,B,R,G,B,... for 24-bit RGB color. Each scanline is an 20936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanearray of data type JSAMPLE --- which is typically "unsigned char", unless 21036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneyou've changed jmorecfg.h. (You can also change the RGB pixel layout, say 21136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneto B,G,R order, by modifying jmorecfg.h. But see the restrictions listed in 21236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethat file before doing so.) 21336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 21436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneA 2-D array of pixels is formed by making a list of pointers to the starts of 21536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanescanlines; so the scanlines need not be physically adjacent in memory. Even 21636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneif you process just one scanline at a time, you must make a one-element 217bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanepointer array to conform to this structure. Pointers to JSAMPLE rows are of 218bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanetype JSAMPROW, and the pointer to the pointer array is of type JSAMPARRAY. 21936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 22036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe library accepts or supplies one or more complete scanlines per call. 22136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIt is not possible to process part of a row at a time. Scanlines are always 22236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneprocessed top-to-bottom. You can process an entire image in one call if you 22336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanehave it all in memory, but usually it's simplest to process one scanline at 22436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanea time. 22536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 22636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneFor best results, source data values should have the precision specified by 22736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneBITS_IN_JSAMPLE (normally 8 bits). For instance, if you choose to compress 22836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedata that's only 6 bits/channel, you should left-justify each value in a 22936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanebyte before passing it to the compressor. If you need to compress data 23036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethat has more than 8 bits/channel, compile with BITS_IN_JSAMPLE = 12. 23136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane(See "Library compile-time options", later.) 23236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 233489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lane 23436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe data format returned by the decompressor is the same in all details, 235489583f5165e05d37302e8eeec58104ea0109127Thomas G. Laneexcept that colormapped output is supported. (Again, a JPEG file is never 236489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanecolormapped. But you can ask the decompressor to perform on-the-fly color 237489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanequantization to deliver colormapped output.) If you request colormapped 23836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneoutput then the returned data array contains a single JSAMPLE per pixel; 23936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneits value is an index into a color map. The color map is represented as 24036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanea 2-D JSAMPARRAY in which each row holds the values of one color component, 24136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethat is, colormap[i][j] is the value of the i'th color component for pixel 24236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanevalue (map index) j. Note that since the colormap indexes are stored in 24336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJSAMPLEs, the maximum number of colors is limited by the size of JSAMPLE 24436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane(ie, at most 256 colors for an 8-bit JPEG library). 24536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 24636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 24736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneCompression details 24836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane------------------- 24936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 25036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneHere we revisit the JPEG compression outline given in the overview. 25136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 25236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane1. Allocate and initialize a JPEG compression object. 25336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 254bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneA JPEG compression object is a "struct jpeg_compress_struct". (It also has 255bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanea bunch of subsidiary structures which are allocated via malloc(), but the 256bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneapplication doesn't control those directly.) This struct can be just a local 257bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanevariable in the calling routine, if a single routine is going to execute the 258bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanewhole JPEG compression sequence. Otherwise it can be static or allocated 259bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanefrom malloc(). 26036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 26136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou will also need a structure representing a JPEG error handler. The part 26236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneof this that the library cares about is a "struct jpeg_error_mgr". If you 26336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneare providing your own error handler, you'll typically want to embed the 26436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_error_mgr struct in a larger structure; this is discussed later under 26536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane"Error handling". For now we'll assume you are just using the default error 26636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanehandler. The default error handler will print JPEG error/warning messages 26736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneon stderr, and it will call exit() if a fatal error occurs. 26836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 26936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou must initialize the error handler structure, store a pointer to it into 27036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe JPEG object's "err" field, and then call jpeg_create_compress() to 27136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneinitialize the rest of the JPEG object. 27236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 27336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTypical code for this step, if you are using the default error handler, is 27436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 275b775351012af176720429ac21d11682a0b75b4b7DRC struct jpeg_compress_struct cinfo; 276b775351012af176720429ac21d11682a0b75b4b7DRC struct jpeg_error_mgr jerr; 277b775351012af176720429ac21d11682a0b75b4b7DRC ... 278b775351012af176720429ac21d11682a0b75b4b7DRC cinfo.err = jpeg_std_error(&jerr); 279b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_create_compress(&cinfo); 28036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 28136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_create_compress allocates a small amount of memory, so it could fail 28236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneif you are out of memory. In that case it will exit via the error handler; 28336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethat's why the error handler must be initialized first. 28436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 28536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 28636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane2. Specify the destination for the compressed data (eg, a file). 28736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 28836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAs previously mentioned, the JPEG library delivers compressed data to a 28936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane"data destination" module. The library includes one data destination 29036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemodule which knows how to write to a stdio stream. You can use your own 29136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedestination module if you want to do something else, as discussed later. 29236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 29336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf you use the standard destination module, you must open the target stdio 29436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanestream beforehand. Typical code for this step looks like: 29536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 2966eb7d3798b5a79347c62825fc4c16f7ce673bdd0Alex Naidis FILE *outfile; 297b775351012af176720429ac21d11682a0b75b4b7DRC ... 298b775351012af176720429ac21d11682a0b75b4b7DRC if ((outfile = fopen(filename, "wb")) == NULL) { 299b775351012af176720429ac21d11682a0b75b4b7DRC fprintf(stderr, "can't open %s\n", filename); 300b775351012af176720429ac21d11682a0b75b4b7DRC exit(1); 301b775351012af176720429ac21d11682a0b75b4b7DRC } 302b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_stdio_dest(&cinfo, outfile); 30336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 30436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewhere the last line invokes the standard destination module. 30536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 30636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneWARNING: it is critical that the binary compressed data be delivered to the 30736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneoutput file unchanged. On non-Unix systems the stdio library may perform 30836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanenewline translation or otherwise corrupt binary data. To suppress this 30936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanebehavior, you may need to use a "b" option to fopen (as shown above), or use 31036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesetmode() or another routine to put the stdio stream in binary mode. See 31136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecjpeg.c and djpeg.c for code that has been found to work on many systems. 31236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 31336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou can select the data destination after setting other parameters (step 3), 31436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneif that's more convenient. You may not change the destination between 31536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecalling jpeg_start_compress() and jpeg_finish_compress(). 31636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 31736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 31836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane3. Set parameters for compression, including image size & colorspace. 31936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 32036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou must supply information about the source image by setting the following 32136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefields in the JPEG object (cinfo structure): 32236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 323b775351012af176720429ac21d11682a0b75b4b7DRC image_width Width of image, in pixels 324b775351012af176720429ac21d11682a0b75b4b7DRC image_height Height of image, in pixels 325b775351012af176720429ac21d11682a0b75b4b7DRC input_components Number of color channels (samples per pixel) 326b775351012af176720429ac21d11682a0b75b4b7DRC in_color_space Color space of source image 32736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 32836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe image dimensions are, hopefully, obvious. JPEG supports image dimensions 32936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneof 1 to 64K pixels in either direction. The input color space is typically 33036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneRGB or grayscale, and input_components is 3 or 1 accordingly. (See "Special 33136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecolor spaces", later, for more info.) The in_color_space field must be 33236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneassigned one of the J_COLOR_SPACE enum constants, typically JCS_RGB or 33336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJCS_GRAYSCALE. 33436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 33536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJPEG has a large number of compression parameters that determine how the 33636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneimage is encoded. Most applications don't need or want to know about all 33736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethese parameters. You can set all the parameters to reasonable defaults by 33836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecalling jpeg_set_defaults(); then, if there are particular values you want 33936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneto change, you can do so after that. The "Compression parameter selection" 34036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesection tells about all the parameters. 34136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 34236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou must set in_color_space correctly before calling jpeg_set_defaults(), 34336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanebecause the defaults depend on the source image colorspace. However the 34436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneother three source image parameters need not be valid until you call 34536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_start_compress(). There's no harm in calling jpeg_set_defaults() more 34636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethan once, if that happens to be convenient. 34736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 34836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTypical code for a 24-bit RGB source image is 34936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 350b775351012af176720429ac21d11682a0b75b4b7DRC cinfo.image_width = Width; /* image width and height, in pixels */ 351b775351012af176720429ac21d11682a0b75b4b7DRC cinfo.image_height = Height; 352b775351012af176720429ac21d11682a0b75b4b7DRC cinfo.input_components = 3; /* # of color components per pixel */ 353b775351012af176720429ac21d11682a0b75b4b7DRC cinfo.in_color_space = JCS_RGB; /* colorspace of input image */ 35436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 355b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_set_defaults(&cinfo); 356b775351012af176720429ac21d11682a0b75b4b7DRC /* Make optional parameter settings here */ 35736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 35836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 35936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane4. jpeg_start_compress(...); 36036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 36136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAfter you have established the data destination and set all the necessary 36236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesource image info and other parameters, call jpeg_start_compress() to begin 36336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanea compression cycle. This will initialize internal state, allocate working 36436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanestorage, and emit the first few bytes of the JPEG datastream header. 36536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 36636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTypical code: 36736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 368b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_start_compress(&cinfo, TRUE); 36936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 37036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe "TRUE" parameter ensures that a complete JPEG interchange datastream 37136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewill be written. This is appropriate in most cases. If you think you might 37236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewant to use an abbreviated datastream, read the section on abbreviated 37336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedatastreams, below. 37436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 37536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneOnce you have called jpeg_start_compress(), you may not alter any JPEG 37636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneparameters or other fields of the JPEG object until you have completed 37736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe compression cycle. 37836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 37936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 38036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane5. while (scan lines remain to be written) 381b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_write_scanlines(...); 38236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 38336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneNow write all the required image data by calling jpeg_write_scanlines() 38436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneone or more times. You can pass one or more scanlines in each call, up 38536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneto the total image height. In most applications it is convenient to pass 38636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejust one or a few scanlines at a time. The expected format for the passed 38736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedata is discussed under "Data formats", above. 38836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 38936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneImage data should be written in top-to-bottom scanline order. The JPEG spec 39036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecontains some weasel wording about how top and bottom are application-defined 39136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneterms (a curious interpretation of the English language...) but if you want 39236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneyour files to be compatible with everyone else's, you WILL use top-to-bottom 39336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneorder. If the source data must be read in bottom-to-top order, you can use 39436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe JPEG library's virtual array mechanism to invert the data efficiently. 39536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneExamples of this can be found in the sample application cjpeg. 39636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 39736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe library maintains a count of the number of scanlines written so far 39836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanein the next_scanline field of the JPEG object. Usually you can just use 39936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethis variable as the loop counter, so that the loop test looks like 40036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane"while (cinfo.next_scanline < cinfo.image_height)". 40136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 40236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneCode for this step depends heavily on the way that you store the source data. 40336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneexample.c shows the following code for the case of a full-size 2-D source 40436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanearray containing 3-byte RGB pixels: 40536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 406b775351012af176720429ac21d11682a0b75b4b7DRC JSAMPROW row_pointer[1]; /* pointer to a single row */ 407b775351012af176720429ac21d11682a0b75b4b7DRC int row_stride; /* physical row width in buffer */ 40836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 409b775351012af176720429ac21d11682a0b75b4b7DRC row_stride = image_width * 3; /* JSAMPLEs per row in image_buffer */ 41036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 411b775351012af176720429ac21d11682a0b75b4b7DRC while (cinfo.next_scanline < cinfo.image_height) { 412b775351012af176720429ac21d11682a0b75b4b7DRC row_pointer[0] = & image_buffer[cinfo.next_scanline * row_stride]; 413b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_write_scanlines(&cinfo, row_pointer, 1); 414b775351012af176720429ac21d11682a0b75b4b7DRC } 41536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 41636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_write_scanlines() returns the number of scanlines actually written. 41736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThis will normally be equal to the number passed in, so you can usually 41836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneignore the return value. It is different in just two cases: 41936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * If you try to write more scanlines than the declared image height, 42036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane the additional scanlines are ignored. 42136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * If you use a suspending data destination manager, output buffer overrun 42236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane will cause the compressor to return before accepting all the passed lines. 42336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane This feature is discussed under "I/O suspension", below. The normal 42436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane stdio destination manager will NOT cause this to happen. 42536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIn any case, the return value is the same as the change in the value of 42636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanenext_scanline. 42736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 42836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 42936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane6. jpeg_finish_compress(...); 43036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 43136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAfter all the image data has been written, call jpeg_finish_compress() to 43236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecomplete the compression cycle. This step is ESSENTIAL to ensure that the 43336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanelast bufferload of data is written to the data destination. 43436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_finish_compress() also releases working memory associated with the JPEG 43536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneobject. 43636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 43736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTypical code: 43836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 439b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_finish_compress(&cinfo); 44036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 44136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf using the stdio destination manager, don't forget to close the output 4425ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanestdio stream (if necessary) afterwards. 44336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 44436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf you have requested a multi-pass operating mode, such as Huffman code 44536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneoptimization, jpeg_finish_compress() will perform the additional passes using 44636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedata buffered by the first pass. In this case jpeg_finish_compress() may take 44736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanequite a while to complete. With the default compression parameters, this will 44836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanenot happen. 44936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 45036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIt is an error to call jpeg_finish_compress() before writing the necessary 45136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanetotal number of scanlines. If you wish to abort compression, call 45236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_abort() as discussed below. 45336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 45436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAfter completing a compression cycle, you may dispose of the JPEG object 45536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneas discussed next, or you may use it to compress another image. In that case 45636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanereturn to step 2, 3, or 4 as appropriate. If you do not change the 45736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedestination manager, the new datastream will be written to the same target. 45836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf you do not change any JPEG parameters, the new datastream will be written 45936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewith the same parameters as before. Note that you can change the input image 46036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedimensions freely between cycles, but if you change the input colorspace, you 46136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneshould call jpeg_set_defaults() to adjust for the new colorspace; and then 46236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneyou'll need to repeat all of step 3. 46336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 46436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 46536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane7. Release the JPEG compression object. 46636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 46736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneWhen you are done with a JPEG compression object, destroy it by calling 4685ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanejpeg_destroy_compress(). This will free all subsidiary memory (regardless of 4695ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanethe previous state of the object). Or you can call jpeg_destroy(), which 4705ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneworks for either compression or decompression objects --- this may be more 4715ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneconvenient if you are sharing code between compression and decompression 4725ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanecases. (Actually, these routines are equivalent except for the declared type 4735ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneof the passed pointer. To avoid gripes from ANSI C compilers, jpeg_destroy() 4745ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneshould be passed a j_common_ptr.) 47536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 47636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf you allocated the jpeg_compress_struct structure from malloc(), freeing 47736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneit is your responsibility --- jpeg_destroy() won't. Ditto for the error 47836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanehandler structure. 47936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 48036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTypical code: 48136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 482b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_destroy_compress(&cinfo); 48336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 48436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 48536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane8. Aborting. 48636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 48736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf you decide to abort a compression cycle before finishing, you can clean up 48836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanein either of two ways: 48936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 49036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane* If you don't need the JPEG object any more, just call 49136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane jpeg_destroy_compress() or jpeg_destroy() to release memory. This is 49236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane legitimate at any point after calling jpeg_create_compress() --- in fact, 49336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane it's safe even if jpeg_create_compress() fails. 49436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 4955ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane* If you want to re-use the JPEG object, call jpeg_abort_compress(), or call 49636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane jpeg_abort() which works on both compression and decompression objects. 49736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane This will return the object to an idle state, releasing any working memory. 49836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane jpeg_abort() is allowed at any time after successful object creation. 49936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 50036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneNote that cleaning up the data destination, if required, is your 5015ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneresponsibility; neither of these routines will call term_destination(). 5025ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane(See "Compressed data handling", below, for more about that.) 5035ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 5045ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanejpeg_destroy() and jpeg_abort() are the only safe calls to make on a JPEG 5055ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneobject that has reported an error by calling error_exit (see "Error handling" 5065ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanefor more info). The internal state of such an object is likely to be out of 5075ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanewhack. Either of these two routines will return the object to a known state. 50836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 50936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 51036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneDecompression details 51136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane--------------------- 51236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 51336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneHere we revisit the JPEG decompression outline given in the overview. 51436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 51536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane1. Allocate and initialize a JPEG decompression object. 51636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 51736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThis is just like initialization for compression, as discussed above, 51836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneexcept that the object is a "struct jpeg_decompress_struct" and you 51936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecall jpeg_create_decompress(). Error handling is exactly the same. 52036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 52136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTypical code: 52236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 523b775351012af176720429ac21d11682a0b75b4b7DRC struct jpeg_decompress_struct cinfo; 524b775351012af176720429ac21d11682a0b75b4b7DRC struct jpeg_error_mgr jerr; 525b775351012af176720429ac21d11682a0b75b4b7DRC ... 526b775351012af176720429ac21d11682a0b75b4b7DRC cinfo.err = jpeg_std_error(&jerr); 527b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_create_decompress(&cinfo); 52836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 52936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane(Both here and in the IJG code, we usually use variable name "cinfo" for 53036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneboth compression and decompression objects.) 53136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 53236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 53336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane2. Specify the source of the compressed data (eg, a file). 53436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 53536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAs previously mentioned, the JPEG library reads compressed data from a "data 53636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesource" module. The library includes one data source module which knows how 53736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneto read from a stdio stream. You can use your own source module if you want 53836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneto do something else, as discussed later. 53936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 54036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf you use the standard source module, you must open the source stdio stream 54136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanebeforehand. Typical code for this step looks like: 54236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 5436eb7d3798b5a79347c62825fc4c16f7ce673bdd0Alex Naidis FILE *infile; 544b775351012af176720429ac21d11682a0b75b4b7DRC ... 545b775351012af176720429ac21d11682a0b75b4b7DRC if ((infile = fopen(filename, "rb")) == NULL) { 546b775351012af176720429ac21d11682a0b75b4b7DRC fprintf(stderr, "can't open %s\n", filename); 547b775351012af176720429ac21d11682a0b75b4b7DRC exit(1); 548b775351012af176720429ac21d11682a0b75b4b7DRC } 549b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_stdio_src(&cinfo, infile); 55036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 55136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewhere the last line invokes the standard source module. 55236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 55336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneWARNING: it is critical that the binary compressed data be read unchanged. 55436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneOn non-Unix systems the stdio library may perform newline translation or 55536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneotherwise corrupt binary data. To suppress this behavior, you may need to use 55636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanea "b" option to fopen (as shown above), or use setmode() or another routine to 55736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneput the stdio stream in binary mode. See cjpeg.c and djpeg.c for code that 55836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanehas been found to work on many systems. 55936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 56036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou may not change the data source between calling jpeg_read_header() and 56136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_finish_decompress(). If you wish to read a series of JPEG images from 56236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanea single source file, you should repeat the jpeg_read_header() to 56336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_finish_decompress() sequence without reinitializing either the JPEG 56436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneobject or the data source module; this prevents buffered input data from 56536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanebeing discarded. 56636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 56736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 56836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane3. Call jpeg_read_header() to obtain image info. 56936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 57036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTypical code for this step is just 57136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 572b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_read_header(&cinfo, TRUE); 57336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 57436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThis will read the source datastream header markers, up to the beginning 57536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneof the compressed data proper. On return, the image dimensions and other 57636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneinfo have been stored in the JPEG object. The application may wish to 57736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneconsult this information before selecting decompression parameters. 57836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 57936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneMore complex code is necessary if 58036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * A suspending data source is used --- in that case jpeg_read_header() 58136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane may return before it has read all the header data. See "I/O suspension", 58236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane below. The normal stdio source manager will NOT cause this to happen. 58336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * Abbreviated JPEG files are to be processed --- see the section on 58436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane abbreviated datastreams. Standard applications that deal only in 58536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane interchange JPEG files need not be concerned with this case either. 58636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 58736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIt is permissible to stop at this point if you just wanted to find out the 58836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneimage dimensions and other header info for a JPEG file. In that case, 58936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecall jpeg_destroy() when you are done with the JPEG object, or call 59036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_abort() to return it to an idle state before selecting a new data 59136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesource and reading another header. 59236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 59336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 59436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane4. Set parameters for decompression. 59536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 59636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_read_header() sets appropriate default decompression parameters based on 59736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe properties of the image (in particular, its colorspace). However, you 59836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemay well want to alter these defaults before beginning the decompression. 59936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneFor example, the default is to produce full color output from a color file. 60036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf you want colormapped output you must ask for it. Other options allow the 60136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanereturned image to be scaled and allow various speed/quality tradeoffs to be 60236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneselected. "Decompression parameter selection", below, gives details. 60336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 60436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf the defaults are appropriate, nothing need be done at this step. 60536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 60636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneNote that all default values are set by each call to jpeg_read_header(). 60736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf you reuse a decompression object, you cannot expect your parameter 60836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesettings to be preserved across cycles, as you can for compression. 609bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneYou must set desired parameter values each time. 61036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 61136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 61236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane5. jpeg_start_decompress(...); 61336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 61436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneOnce the parameter values are satisfactory, call jpeg_start_decompress() to 61536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanebegin decompression. This will initialize internal state, allocate working 61636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanememory, and prepare for returning data. 61736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 61836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTypical code is just 61936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 620b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_start_decompress(&cinfo); 62136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 62236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf you have requested a multi-pass operating mode, such as 2-pass color 62336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanequantization, jpeg_start_decompress() will do everything needed before data 62436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneoutput can begin. In this case jpeg_start_decompress() may take quite a while 625bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneto complete. With a single-scan (non progressive) JPEG file and default 62636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedecompression parameters, this will not happen; jpeg_start_decompress() will 62736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanereturn quickly. 62836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 62936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAfter this call, the final output image dimensions, including any requested 63036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanescaling, are available in the JPEG object; so is the selected colormap, if 63136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecolormapped output has been requested. Useful fields include 63236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 633b775351012af176720429ac21d11682a0b75b4b7DRC output_width image width and height, as scaled 634b775351012af176720429ac21d11682a0b75b4b7DRC output_height 635b775351012af176720429ac21d11682a0b75b4b7DRC out_color_components # of color components in out_color_space 636b775351012af176720429ac21d11682a0b75b4b7DRC output_components # of color components returned per pixel 637b775351012af176720429ac21d11682a0b75b4b7DRC colormap the selected colormap, if any 638b775351012af176720429ac21d11682a0b75b4b7DRC actual_number_of_colors number of entries in colormap 63936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 64036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneoutput_components is 1 (a colormap index) when quantizing colors; otherwise it 64136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneequals out_color_components. It is the number of JSAMPLE values that will be 64236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneemitted per pixel in the output arrays. 64336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 64436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTypically you will need to allocate data buffers to hold the incoming image. 64536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou will need output_width * output_components JSAMPLEs per scanline in your 64636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneoutput buffer, and a total of output_height scanlines will be returned. 64736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 64836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneNote: if you are using the JPEG library's internal memory manager to allocate 64936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedata buffers (as djpeg does), then the manager's protocol requires that you 65036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanerequest large buffers *before* calling jpeg_start_decompress(). This is a 65136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanelittle tricky since the output_XXX fields are not normally valid then. You 65236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecan make them valid by calling jpeg_calc_output_dimensions() after setting the 65336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanerelevant parameters (scaling, output color space, and quantization flag). 65436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 65536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 65636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane6. while (scan lines remain to be read) 657b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_read_scanlines(...); 65836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 65936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneNow you can read the decompressed image data by calling jpeg_read_scanlines() 66036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneone or more times. At each call, you pass in the maximum number of scanlines 66136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneto be read (ie, the height of your working buffer); jpeg_read_scanlines() 66236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewill return up to that many lines. The return value is the number of lines 66336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneactually read. The format of the returned data is discussed under "Data 664a8b67c4fbbfde9b4b4e03f2dea8f4f0b1900fc33Thomas G. Laneformats", above. Don't forget that grayscale and color JPEGs will return 665a8b67c4fbbfde9b4b4e03f2dea8f4f0b1900fc33Thomas G. Lanedifferent data formats! 66636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 66736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneImage data is returned in top-to-bottom scanline order. If you must write 66836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneout the image in bottom-to-top order, you can use the JPEG library's virtual 66936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanearray mechanism to invert the data efficiently. Examples of this can be 67036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefound in the sample application djpeg. 67136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 67236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe library maintains a count of the number of scanlines returned so far 67336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanein the output_scanline field of the JPEG object. Usually you can just use 67436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethis variable as the loop counter, so that the loop test looks like 67536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane"while (cinfo.output_scanline < cinfo.output_height)". (Note that the test 67636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneshould NOT be against image_height, unless you never use scaling. The 67736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneimage_height field is the height of the original unscaled image.) 6789ba2f5ed3649fb6de83d3c16e4dba1443aaca983Thomas G. LaneThe return value always equals the change in the value of output_scanline. 67936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 68036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf you don't use a suspending data source, it is safe to assume that 68136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_read_scanlines() reads at least one scanline per call, until the 682489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanebottom of the image has been reached. 683489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lane 684489583f5165e05d37302e8eeec58104ea0109127Thomas G. LaneIf you use a buffer larger than one scanline, it is NOT safe to assume that 6855ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanejpeg_read_scanlines() fills it. (The current implementation returns only a 6865ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanefew scanlines per call, no matter how large a buffer you pass.) So you must 6875ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanealways provide a loop that calls jpeg_read_scanlines() repeatedly until the 6885ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanewhole image has been read. 68936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 69036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 69136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane7. jpeg_finish_decompress(...); 69236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 69336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAfter all the image data has been read, call jpeg_finish_decompress() to 69436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecomplete the decompression cycle. This causes working memory associated 69536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewith the JPEG object to be released. 69636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 69736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTypical code: 69836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 699b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_finish_decompress(&cinfo); 70036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 70136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf using the stdio source manager, don't forget to close the source stdio 70236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanestream if necessary. 70336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 70436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIt is an error to call jpeg_finish_decompress() before reading the correct 7055ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanetotal number of scanlines. If you wish to abort decompression, call 70636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_abort() as discussed below. 70736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 70836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAfter completing a decompression cycle, you may dispose of the JPEG object as 70936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanediscussed next, or you may use it to decompress another image. In that case 71036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanereturn to step 2 or 3 as appropriate. If you do not change the source 71136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemanager, the next image will be read from the same source. 71236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 71336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 71436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane8. Release the JPEG decompression object. 71536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 71636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneWhen you are done with a JPEG decompression object, destroy it by calling 71736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_destroy_decompress() or jpeg_destroy(). The previous discussion of 71836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedestroying compression objects applies here too. 71936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 72036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTypical code: 72136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 722b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_destroy_decompress(&cinfo); 72336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 72436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 72536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane9. Aborting. 72636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 72736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou can abort a decompression cycle by calling jpeg_destroy_decompress() or 72836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_destroy() if you don't need the JPEG object any more, or 72936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_abort_decompress() or jpeg_abort() if you want to reuse the object. 73036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe previous discussion of aborting compression cycles applies here too. 73136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 73236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 7330ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCPartial image decompression 7340ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRC--------------------------- 735ac30a1bf12751bd82e56158eb9456a28d9c086f3DRC 7360ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCPartial image decompression is convenient for performance-critical applications 7370ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCthat wish to view only a portion of a large JPEG image without decompressing 7380ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCthe whole thing. It it also useful in memory-constrained environments (such as 7390ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCon mobile devices.) This library provides the following functions to support 7400ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCpartial image decompression: 7410ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRC 7420ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRC1. Skipping rows when decompressing 7430ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRC 7440ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRC jpeg_skip_scanlines(j_decompress_ptr cinfo, JDIMENSION num_lines); 745ac30a1bf12751bd82e56158eb9456a28d9c086f3DRC 746ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCThis function provides application programmers with the ability to skip over 7470ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCmultiple rows in the JPEG image. 748ac30a1bf12751bd82e56158eb9456a28d9c086f3DRC 749ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCSuspending data sources are not supported by this function. Calling 750ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCjpeg_skip_scanlines() with a suspending data source will result in undefined 751ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCbehavior. 752ac30a1bf12751bd82e56158eb9456a28d9c086f3DRC 753ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCjpeg_skip_scanlines() will not allow skipping past the bottom of the image. If 754ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCthe value of num_lines is large enough to skip past the bottom of the image, 755ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCthen the function will skip to the end of the image instead. 756ac30a1bf12751bd82e56158eb9456a28d9c086f3DRC 757ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCIf the value of num_lines is valid, then jpeg_skip_scanlines() will always 758ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCskip all of the input rows requested. There is no need to inspect the return 759ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCvalue of the function in that case. 760ac30a1bf12751bd82e56158eb9456a28d9c086f3DRC 761ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCBest results will be achieved by calling jpeg_skip_scanlines() for large chunks 762ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCof rows. The function should be viewed as a way to quickly jump to a 763ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCparticular vertical offset in the JPEG image in order to decode a subset of the 764ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCimage. Used in this manner, it will provide significant performance 765ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCimprovements. 766ac30a1bf12751bd82e56158eb9456a28d9c086f3DRC 767ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCCalling jpeg_skip_scanlines() for small values of num_lines has several 768ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCpotential drawbacks: 769ac30a1bf12751bd82e56158eb9456a28d9c086f3DRC 1) JPEG decompression occurs in blocks, so if jpeg_skip_scanlines() is 770ac30a1bf12751bd82e56158eb9456a28d9c086f3DRC called from the middle of a decompression block, then it is likely that 771ac30a1bf12751bd82e56158eb9456a28d9c086f3DRC much of the decompression work has already been done for the first 772ac30a1bf12751bd82e56158eb9456a28d9c086f3DRC couple of rows that need to be skipped. 773ac30a1bf12751bd82e56158eb9456a28d9c086f3DRC 2) When this function returns, it must leave the decompressor in a state 774ac30a1bf12751bd82e56158eb9456a28d9c086f3DRC such that it is ready to read the next line. This may involve 775ac30a1bf12751bd82e56158eb9456a28d9c086f3DRC decompressing a block that must be partially skipped. 776ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCThese issues are especially tricky for cases in which upsampling requires 777ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCcontext rows. In the worst case, jpeg_skip_scanlines() will perform similarly 778ac30a1bf12751bd82e56158eb9456a28d9c086f3DRCto jpeg_read_scanlines() (since it will actually call jpeg_read_scanlines().) 779ac30a1bf12751bd82e56158eb9456a28d9c086f3DRC 7800ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRC2. Decompressing partial scanlines 7810ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRC 7820ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRC jpeg_crop_scanline (j_decompress_ptr cinfo, JDIMENSION *xoffset, 7830ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRC JDIMENSION *width) 7840ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRC 7850ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCThis function provides application programmers with the ability to decompress 7860ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRConly a portion of each row in the JPEG image. It must be called after 7870ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCjpeg_start_decompress() and before any calls to jpeg_read_scanlines() or 7880ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCjpeg_skip_scanlines(). 7890ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRC 7900ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCIf xoffset and width do not form a valid subset of the image row, then this 7910ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCfunction will generate an error. Note that if the output image is scaled, then 7920ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCxoffset and width are relative to the scaled image dimensions. 7930ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRC 7940ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCxoffset and width are passed by reference because xoffset must fall on an iMCU 7950ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCboundary. If it doesn't, then it will be moved left to the nearest iMCU 7960ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCboundary, and width will be increased accordingly. If the calling program does 7970ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCnot like the adjusted values of xoffset and width, then it can call 7980ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCjpeg_crop_scanline() again with new values (for instance, if it wants to move 7990ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCxoffset to the nearest iMCU boundary to the right instead of to the left.) 8000ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRC 8010ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCAfter calling this function, cinfo->output_width will be set to the adjusted 8020ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCwidth. This value should be used when allocating an output buffer to pass to 8030ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCjpeg_read_scanlines(). 8040ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRC 8050ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCThe output image from a partial-width decompression will be identical to the 8060ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCcorresponding image region from a full decode, with one exception: The "fancy" 8070ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRC(smooth) h2v2 (4:2:0) and h2v1 (4:2:2) upsampling algorithms fill in the 8080ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCmissing chroma components by averaging the chroma components from neighboring 8090ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCpixels, except on the right and left edges of the image (where there are no 8100ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCneighboring pixels.) When performing a partial-width decompression, these 8110ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRC"fancy" upsampling algorithms may treat the left and right edges of the partial 8120ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCimage region as if they are the left and right edges of the image, meaning that 8130ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCthe upsampling algorithm may be simplified. The result is that the pixels on 8140ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCthe left or right edge of the partial image may not be exactly identical to the 8150ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRCcorresponding pixels in the original image. 8160ef076fb7b326dc201b4ab3bd30fefd4e35ad1c4DRC 817ac30a1bf12751bd82e56158eb9456a28d9c086f3DRC 81836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneMechanics of usage: include files, linking, etc 81936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane----------------------------------------------- 82036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 82136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneApplications using the JPEG library should include the header file jpeglib.h 82236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneto obtain declarations of data types and routines. Before including 82336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeglib.h, include system headers that define at least the typedefs FILE and 82436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesize_t. On ANSI-conforming systems, including <stdio.h> is sufficient; on 82536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneolder Unix systems, you may need <sys/types.h> to define size_t. 82636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 82736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf the application needs to refer to individual JPEG library error codes, also 82836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneinclude jerror.h to define those symbols. 82936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 83036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeglib.h indirectly includes the files jconfig.h and jmorecfg.h. If you are 83136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneinstalling the JPEG header files in a system directory, you will want to 83236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneinstall all four files: jpeglib.h, jerror.h, jconfig.h, jmorecfg.h. 83336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 83436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe most convenient way to include the JPEG code into your executable program 83536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneis to prepare a library file ("libjpeg.a", or a corresponding name on non-Unix 83636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemachines) and reference it at your link step. If you use only half of the 83736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanelibrary (only compression or only decompression), only that much code will be 83836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneincluded from the library, unless your linker is hopelessly brain-damaged. 8395996a25e2f50d20d6a8f09830724035b49c3927bGuido VollbedingThe supplied makefiles build libjpeg.a automatically (see install.txt). 84036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 8415ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneWhile you can build the JPEG library as a shared library if the whim strikes 8425ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneyou, we don't really recommend it. The trouble with shared libraries is that 8435ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneat some point you'll probably try to substitute a new version of the library 8445ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanewithout recompiling the calling applications. That generally doesn't work 8455ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanebecause the parameter struct declarations usually change with each new 8465ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneversion. In other words, the library's API is *not* guaranteed binary 8475ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanecompatible across versions; we only try to ensure source-code compatibility. 8485ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane(In hindsight, it might have been smarter to hide the parameter structs from 8495ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneapplications and introduce a ton of access functions instead. Too late now, 8505ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanehowever.) 8515ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 85236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIt may be worth pointing out that the core JPEG library does not actually 85336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanerequire the stdio library: only the default source/destination managers and 85436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneerror handler need it. You can use the library in a stdio-less environment 85536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneif you replace those modules and use jmemnobs.c (or another memory manager of 85636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneyour own devising). More info about the minimum system library requirements 85736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemay be found in jinclude.h. 85836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 85936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 86036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneADVANCED FEATURES 86136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane================= 86236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 86336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneCompression parameter selection 86436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane------------------------------- 86536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 86636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThis section describes all the optional parameters you can set for JPEG 86736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecompression, as well as the "helper" routines provided to assist in this 86836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanetask. Proper setting of some parameters requires detailed understanding 86936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneof the JPEG standard; if you don't know what a parameter is for, it's best 8706eb7d3798b5a79347c62825fc4c16f7ce673bdd0Alex Naidisnot to mess with it! See REFERENCES in the README.ijg file for pointers to 87136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemore info about JPEG. 87236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 87336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIt's a good idea to call jpeg_set_defaults() first, even if you plan to set 87436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneall the parameters; that way your code is more likely to work with future JPEG 87536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanelibraries that have additional parameters. For the same reason, we recommend 87636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneyou use a helper routine where one is provided, in preference to twiddling 87736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecinfo fields directly. 87836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 87936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe helper routines are: 88036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 88136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_set_defaults (j_compress_ptr cinfo) 882b775351012af176720429ac21d11682a0b75b4b7DRC This routine sets all JPEG parameters to reasonable defaults, using 883b775351012af176720429ac21d11682a0b75b4b7DRC only the input image's color space (field in_color_space, which must 884b775351012af176720429ac21d11682a0b75b4b7DRC already be set in cinfo). Many applications will only need to use 885b775351012af176720429ac21d11682a0b75b4b7DRC this routine and perhaps jpeg_set_quality(). 88636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 88736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_set_colorspace (j_compress_ptr cinfo, J_COLOR_SPACE colorspace) 888b775351012af176720429ac21d11682a0b75b4b7DRC Sets the JPEG file's colorspace (field jpeg_color_space) as specified, 889b775351012af176720429ac21d11682a0b75b4b7DRC and sets other color-space-dependent parameters appropriately. See 890b775351012af176720429ac21d11682a0b75b4b7DRC "Special color spaces", below, before using this. A large number of 891b775351012af176720429ac21d11682a0b75b4b7DRC parameters, including all per-component parameters, are set by this 892b775351012af176720429ac21d11682a0b75b4b7DRC routine; if you want to twiddle individual parameters you should call 893b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_set_colorspace() before rather than after. 89436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 89536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_default_colorspace (j_compress_ptr cinfo) 896b775351012af176720429ac21d11682a0b75b4b7DRC Selects an appropriate JPEG colorspace based on cinfo->in_color_space, 897b775351012af176720429ac21d11682a0b75b4b7DRC and calls jpeg_set_colorspace(). This is actually a subroutine of 898b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_set_defaults(). It's broken out in case you want to change 899b775351012af176720429ac21d11682a0b75b4b7DRC just the colorspace-dependent JPEG parameters. 90036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 90136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_set_quality (j_compress_ptr cinfo, int quality, boolean force_baseline) 902b775351012af176720429ac21d11682a0b75b4b7DRC Constructs JPEG quantization tables appropriate for the indicated 903b775351012af176720429ac21d11682a0b75b4b7DRC quality setting. The quality value is expressed on the 0..100 scale 904b775351012af176720429ac21d11682a0b75b4b7DRC recommended by IJG (cjpeg's "-quality" switch uses this routine). 905b775351012af176720429ac21d11682a0b75b4b7DRC Note that the exact mapping from quality values to tables may change 906b775351012af176720429ac21d11682a0b75b4b7DRC in future IJG releases as more is learned about DCT quantization. 907b775351012af176720429ac21d11682a0b75b4b7DRC If the force_baseline parameter is TRUE, then the quantization table 908b775351012af176720429ac21d11682a0b75b4b7DRC entries are constrained to the range 1..255 for full JPEG baseline 909b775351012af176720429ac21d11682a0b75b4b7DRC compatibility. In the current implementation, this only makes a 910b775351012af176720429ac21d11682a0b75b4b7DRC difference for quality settings below 25, and it effectively prevents 911b775351012af176720429ac21d11682a0b75b4b7DRC very small/low quality files from being generated. The IJG decoder 912b775351012af176720429ac21d11682a0b75b4b7DRC is capable of reading the non-baseline files generated at low quality 913b775351012af176720429ac21d11682a0b75b4b7DRC settings when force_baseline is FALSE, but other decoders may not be. 91436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 91536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_set_linear_quality (j_compress_ptr cinfo, int scale_factor, 916b775351012af176720429ac21d11682a0b75b4b7DRC boolean force_baseline) 917b775351012af176720429ac21d11682a0b75b4b7DRC Same as jpeg_set_quality() except that the generated tables are the 918b775351012af176720429ac21d11682a0b75b4b7DRC sample tables given in the JPEC spec section K.1, multiplied by the 919b775351012af176720429ac21d11682a0b75b4b7DRC specified scale factor (which is expressed as a percentage; thus 920b775351012af176720429ac21d11682a0b75b4b7DRC scale_factor = 100 reproduces the spec's tables). Note that larger 921b775351012af176720429ac21d11682a0b75b4b7DRC scale factors give lower quality. This entry point is useful for 922b775351012af176720429ac21d11682a0b75b4b7DRC conforming to the Adobe PostScript DCT conventions, but we do not 923b775351012af176720429ac21d11682a0b75b4b7DRC recommend linear scaling as a user-visible quality scale otherwise. 924b775351012af176720429ac21d11682a0b75b4b7DRC force_baseline again constrains the computed table entries to 1..255. 92536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 92636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneint jpeg_quality_scaling (int quality) 927b775351012af176720429ac21d11682a0b75b4b7DRC Converts a value on the IJG-recommended quality scale to a linear 928b775351012af176720429ac21d11682a0b75b4b7DRC scaling percentage. Note that this routine may change or go away 929b775351012af176720429ac21d11682a0b75b4b7DRC in future releases --- IJG may choose to adopt a scaling method that 930b775351012af176720429ac21d11682a0b75b4b7DRC can't be expressed as a simple scalar multiplier, in which case the 931b775351012af176720429ac21d11682a0b75b4b7DRC premise of this routine collapses. Caveat user. 93236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 9335996a25e2f50d20d6a8f09830724035b49c3927bGuido Vollbedingjpeg_default_qtables (j_compress_ptr cinfo, boolean force_baseline) 934b775351012af176720429ac21d11682a0b75b4b7DRC [libjpeg v7+ API/ABI emulation only] 935b775351012af176720429ac21d11682a0b75b4b7DRC Set default quantization tables with linear q_scale_factor[] values 936b775351012af176720429ac21d11682a0b75b4b7DRC (see below). 9375996a25e2f50d20d6a8f09830724035b49c3927bGuido Vollbeding 93836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_add_quant_table (j_compress_ptr cinfo, int which_tbl, 939b775351012af176720429ac21d11682a0b75b4b7DRC const unsigned int *basic_table, 940b775351012af176720429ac21d11682a0b75b4b7DRC int scale_factor, boolean force_baseline) 941b775351012af176720429ac21d11682a0b75b4b7DRC Allows an arbitrary quantization table to be created. which_tbl 942b775351012af176720429ac21d11682a0b75b4b7DRC indicates which table slot to fill. basic_table points to an array 943b775351012af176720429ac21d11682a0b75b4b7DRC of 64 unsigned ints given in normal array order. These values are 944b775351012af176720429ac21d11682a0b75b4b7DRC multiplied by scale_factor/100 and then clamped to the range 1..65535 945b775351012af176720429ac21d11682a0b75b4b7DRC (or to 1..255 if force_baseline is TRUE). 946b775351012af176720429ac21d11682a0b75b4b7DRC CAUTION: prior to library version 6a, jpeg_add_quant_table expected 947b775351012af176720429ac21d11682a0b75b4b7DRC the basic table to be given in JPEG zigzag order. If you need to 948b775351012af176720429ac21d11682a0b75b4b7DRC write code that works with either older or newer versions of this 949b775351012af176720429ac21d11682a0b75b4b7DRC routine, you must check the library version number. Something like 950b775351012af176720429ac21d11682a0b75b4b7DRC "#if JPEG_LIB_VERSION >= 61" is the right test. 95136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 952bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_simple_progression (j_compress_ptr cinfo) 953b775351012af176720429ac21d11682a0b75b4b7DRC Generates a default scan script for writing a progressive-JPEG file. 954b775351012af176720429ac21d11682a0b75b4b7DRC This is the recommended method of creating a progressive file, 955b775351012af176720429ac21d11682a0b75b4b7DRC unless you want to make a custom scan sequence. You must ensure that 956b775351012af176720429ac21d11682a0b75b4b7DRC the JPEG color space is set correctly before calling this routine. 95736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 95836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 959bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneCompression parameters (cinfo fields) include: 96036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 9616eb7d3798b5a79347c62825fc4c16f7ce673bdd0Alex Naidisboolean arith_code 9626eb7d3798b5a79347c62825fc4c16f7ce673bdd0Alex Naidis If TRUE, use arithmetic coding. 9636eb7d3798b5a79347c62825fc4c16f7ce673bdd0Alex Naidis If FALSE, use Huffman coding. 9646eb7d3798b5a79347c62825fc4c16f7ce673bdd0Alex Naidis 96536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJ_DCT_METHOD dct_method 966b775351012af176720429ac21d11682a0b75b4b7DRC Selects the algorithm used for the DCT step. Choices are: 967b775351012af176720429ac21d11682a0b75b4b7DRC JDCT_ISLOW: slow but accurate integer algorithm 968b775351012af176720429ac21d11682a0b75b4b7DRC JDCT_IFAST: faster, less accurate integer method 969b775351012af176720429ac21d11682a0b75b4b7DRC JDCT_FLOAT: floating-point method 970b775351012af176720429ac21d11682a0b75b4b7DRC JDCT_DEFAULT: default method (normally JDCT_ISLOW) 971b775351012af176720429ac21d11682a0b75b4b7DRC JDCT_FASTEST: fastest method (normally JDCT_IFAST) 9728940e6ca8628e10b45486fad4572a15b63546eb1DRC In libjpeg-turbo, JDCT_IFAST is generally about 5-15% faster than 9738940e6ca8628e10b45486fad4572a15b63546eb1DRC JDCT_ISLOW when using the x86/x86-64 SIMD extensions (results may vary 9748940e6ca8628e10b45486fad4572a15b63546eb1DRC with other SIMD implementations, or when using libjpeg-turbo without 9758940e6ca8628e10b45486fad4572a15b63546eb1DRC SIMD extensions.) For quality levels of 90 and below, there should be 9768940e6ca8628e10b45486fad4572a15b63546eb1DRC little or no perceptible difference between the two algorithms. For 9778940e6ca8628e10b45486fad4572a15b63546eb1DRC quality levels above 90, however, the difference between JDCT_IFAST and 9788940e6ca8628e10b45486fad4572a15b63546eb1DRC JDCT_ISLOW becomes more pronounced. With quality=97, for instance, 9798940e6ca8628e10b45486fad4572a15b63546eb1DRC JDCT_IFAST incurs generally about a 1-3 dB loss (in PSNR) relative to 9808940e6ca8628e10b45486fad4572a15b63546eb1DRC JDCT_ISLOW, but this can be larger for some images. Do not use 9818940e6ca8628e10b45486fad4572a15b63546eb1DRC JDCT_IFAST with quality levels above 97. The algorithm often 9828940e6ca8628e10b45486fad4572a15b63546eb1DRC degenerates at quality=98 and above and can actually produce a more 98305524e671e42b8a4ba6d0cfab1ffb1af20a29919DRC lossy image than if lower quality levels had been used. Also, in 98405524e671e42b8a4ba6d0cfab1ffb1af20a29919DRC libjpeg-turbo, JDCT_IFAST is not fully accelerated for quality levels 98505524e671e42b8a4ba6d0cfab1ffb1af20a29919DRC above 97, so it will be slower than JDCT_ISLOW. JDCT_FLOAT is mainly a 98605524e671e42b8a4ba6d0cfab1ffb1af20a29919DRC legacy feature. It does not produce significantly more accurate 98705524e671e42b8a4ba6d0cfab1ffb1af20a29919DRC results than the ISLOW method, and it is much slower. The FLOAT method 98805524e671e42b8a4ba6d0cfab1ffb1af20a29919DRC may also give different results on different machines due to varying 98905524e671e42b8a4ba6d0cfab1ffb1af20a29919DRC roundoff behavior, whereas the integer methods should give the same 99005524e671e42b8a4ba6d0cfab1ffb1af20a29919DRC results on all machines. 99136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 992bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneJ_COLOR_SPACE jpeg_color_space 993bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneint num_components 994b775351012af176720429ac21d11682a0b75b4b7DRC The JPEG color space and corresponding number of components; see 995b775351012af176720429ac21d11682a0b75b4b7DRC "Special color spaces", below, for more info. We recommend using 996b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_set_color_space() if you want to change these. 997bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 998bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneboolean optimize_coding 999b775351012af176720429ac21d11682a0b75b4b7DRC TRUE causes the compressor to compute optimal Huffman coding tables 1000b775351012af176720429ac21d11682a0b75b4b7DRC for the image. This requires an extra pass over the data and 1001b775351012af176720429ac21d11682a0b75b4b7DRC therefore costs a good deal of space and time. The default is 1002b775351012af176720429ac21d11682a0b75b4b7DRC FALSE, which tells the compressor to use the supplied or default 1003b775351012af176720429ac21d11682a0b75b4b7DRC Huffman tables. In most cases optimal tables save only a few percent 1004b775351012af176720429ac21d11682a0b75b4b7DRC of file size compared to the default tables. Note that when this is 1005b775351012af176720429ac21d11682a0b75b4b7DRC TRUE, you need not supply Huffman tables at all, and any you do 1006b775351012af176720429ac21d11682a0b75b4b7DRC supply will be overwritten. 1007bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 100836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneunsigned int restart_interval 100936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneint restart_in_rows 1010b775351012af176720429ac21d11682a0b75b4b7DRC To emit restart markers in the JPEG file, set one of these nonzero. 1011b775351012af176720429ac21d11682a0b75b4b7DRC Set restart_interval to specify the exact interval in MCU blocks. 1012b775351012af176720429ac21d11682a0b75b4b7DRC Set restart_in_rows to specify the interval in MCU rows. (If 1013b775351012af176720429ac21d11682a0b75b4b7DRC restart_in_rows is not 0, then restart_interval is set after the 1014b775351012af176720429ac21d11682a0b75b4b7DRC image width in MCUs is computed.) Defaults are zero (no restarts). 1015b775351012af176720429ac21d11682a0b75b4b7DRC One restart marker per MCU row is often a good choice. 1016b775351012af176720429ac21d11682a0b75b4b7DRC NOTE: the overhead of restart markers is higher in grayscale JPEG 1017b775351012af176720429ac21d11682a0b75b4b7DRC files than in color files, and MUCH higher in progressive JPEGs. 1018b775351012af176720429ac21d11682a0b75b4b7DRC If you use restarts, you may want to use larger intervals in those 1019b775351012af176720429ac21d11682a0b75b4b7DRC cases. 102036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 10216eb7d3798b5a79347c62825fc4c16f7ce673bdd0Alex Naidisconst jpeg_scan_info *scan_info 1022bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneint num_scans 1023b775351012af176720429ac21d11682a0b75b4b7DRC By default, scan_info is NULL; this causes the compressor to write a 1024b775351012af176720429ac21d11682a0b75b4b7DRC single-scan sequential JPEG file. If not NULL, scan_info points to 1025b775351012af176720429ac21d11682a0b75b4b7DRC an array of scan definition records of length num_scans. The 1026b775351012af176720429ac21d11682a0b75b4b7DRC compressor will then write a JPEG file having one scan for each scan 1027b775351012af176720429ac21d11682a0b75b4b7DRC definition record. This is used to generate noninterleaved or 1028b775351012af176720429ac21d11682a0b75b4b7DRC progressive JPEG files. The library checks that the scan array 1029b775351012af176720429ac21d11682a0b75b4b7DRC defines a valid JPEG scan sequence. (jpeg_simple_progression creates 1030b775351012af176720429ac21d11682a0b75b4b7DRC a suitable scan definition array for progressive JPEG.) This is 1031b775351012af176720429ac21d11682a0b75b4b7DRC discussed further under "Progressive JPEG support". 1032bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1033bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneint smoothing_factor 1034b775351012af176720429ac21d11682a0b75b4b7DRC If non-zero, the input image is smoothed; the value should be 1 for 1035b775351012af176720429ac21d11682a0b75b4b7DRC minimal smoothing to 100 for maximum smoothing. Consult jcsample.c 1036b775351012af176720429ac21d11682a0b75b4b7DRC for details of the smoothing algorithm. The default is zero. 103736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 103836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneboolean write_JFIF_header 1039b775351012af176720429ac21d11682a0b75b4b7DRC If TRUE, a JFIF APP0 marker is emitted. jpeg_set_defaults() and 1040b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_set_colorspace() set this TRUE if a JFIF-legal JPEG color space 1041b775351012af176720429ac21d11682a0b75b4b7DRC (ie, YCbCr or grayscale) is selected, otherwise FALSE. 104236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 10435ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneUINT8 JFIF_major_version 10445ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneUINT8 JFIF_minor_version 1045b775351012af176720429ac21d11682a0b75b4b7DRC The version number to be written into the JFIF marker. 1046b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_set_defaults() initializes the version to 1.01 (major=minor=1). 1047b775351012af176720429ac21d11682a0b75b4b7DRC You should set it to 1.02 (major=1, minor=2) if you plan to write 1048b775351012af176720429ac21d11682a0b75b4b7DRC any JFIF 1.02 extension markers. 10495ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 105036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneUINT8 density_unit 105136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneUINT16 X_density 105236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneUINT16 Y_density 1053b775351012af176720429ac21d11682a0b75b4b7DRC The resolution information to be written into the JFIF marker; 1054b775351012af176720429ac21d11682a0b75b4b7DRC not used otherwise. density_unit may be 0 for unknown, 1055b775351012af176720429ac21d11682a0b75b4b7DRC 1 for dots/inch, or 2 for dots/cm. The default values are 0,1,1 1056b775351012af176720429ac21d11682a0b75b4b7DRC indicating square pixels of unknown size. 105736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 105836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneboolean write_Adobe_marker 1059b775351012af176720429ac21d11682a0b75b4b7DRC If TRUE, an Adobe APP14 marker is emitted. jpeg_set_defaults() and 1060b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_set_colorspace() set this TRUE if JPEG color space RGB, CMYK, 1061b775351012af176720429ac21d11682a0b75b4b7DRC or YCCK is selected, otherwise FALSE. It is generally a bad idea 1062b775351012af176720429ac21d11682a0b75b4b7DRC to set both write_JFIF_header and write_Adobe_marker. In fact, 1063b775351012af176720429ac21d11682a0b75b4b7DRC you probably shouldn't change the default settings at all --- the 1064b775351012af176720429ac21d11682a0b75b4b7DRC default behavior ensures that the JPEG file's color space can be 1065b775351012af176720429ac21d11682a0b75b4b7DRC recognized by the decoder. 106636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 10676eb7d3798b5a79347c62825fc4c16f7ce673bdd0Alex NaidisJQUANT_TBL *quant_tbl_ptrs[NUM_QUANT_TBLS] 1068b775351012af176720429ac21d11682a0b75b4b7DRC Pointers to coefficient quantization tables, one per table slot, 1069b775351012af176720429ac21d11682a0b75b4b7DRC or NULL if no table is defined for a slot. Usually these should 1070b775351012af176720429ac21d11682a0b75b4b7DRC be set via one of the above helper routines; jpeg_add_quant_table() 1071b775351012af176720429ac21d11682a0b75b4b7DRC is general enough to define any quantization table. The other 1072b775351012af176720429ac21d11682a0b75b4b7DRC routines will set up table slot 0 for luminance quality and table 1073b775351012af176720429ac21d11682a0b75b4b7DRC slot 1 for chrominance. 107436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 10755996a25e2f50d20d6a8f09830724035b49c3927bGuido Vollbedingint q_scale_factor[NUM_QUANT_TBLS] 1076b775351012af176720429ac21d11682a0b75b4b7DRC [libjpeg v7+ API/ABI emulation only] 1077b775351012af176720429ac21d11682a0b75b4b7DRC Linear quantization scaling factors (0-100, default 100) 1078b775351012af176720429ac21d11682a0b75b4b7DRC for use with jpeg_default_qtables(). 1079b775351012af176720429ac21d11682a0b75b4b7DRC See rdswitch.c and cjpeg.c for an example of usage. 1080b775351012af176720429ac21d11682a0b75b4b7DRC Note that the q_scale_factor[] values use "linear" scales, so JPEG 1081b775351012af176720429ac21d11682a0b75b4b7DRC quality levels chosen by the user must be converted to these scales 1082b775351012af176720429ac21d11682a0b75b4b7DRC using jpeg_quality_scaling(). Here is an example that corresponds to 1083b775351012af176720429ac21d11682a0b75b4b7DRC cjpeg -quality 90,70: 10845996a25e2f50d20d6a8f09830724035b49c3927bGuido Vollbeding 1085b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_set_defaults(cinfo); 10865996a25e2f50d20d6a8f09830724035b49c3927bGuido Vollbeding 1087b775351012af176720429ac21d11682a0b75b4b7DRC /* Set luminance quality 90. */ 1088b775351012af176720429ac21d11682a0b75b4b7DRC cinfo->q_scale_factor[0] = jpeg_quality_scaling(90); 1089b775351012af176720429ac21d11682a0b75b4b7DRC /* Set chrominance quality 70. */ 1090b775351012af176720429ac21d11682a0b75b4b7DRC cinfo->q_scale_factor[1] = jpeg_quality_scaling(70); 10915996a25e2f50d20d6a8f09830724035b49c3927bGuido Vollbeding 1092b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_default_qtables(cinfo, force_baseline); 10935996a25e2f50d20d6a8f09830724035b49c3927bGuido Vollbeding 1094b775351012af176720429ac21d11682a0b75b4b7DRC CAUTION: Setting separate quality levels for chrominance and luminance 1095b775351012af176720429ac21d11682a0b75b4b7DRC is mainly only useful if chrominance subsampling is disabled. 2x2 1096b775351012af176720429ac21d11682a0b75b4b7DRC chrominance subsampling (AKA "4:2:0") is the default, but you can 1097b775351012af176720429ac21d11682a0b75b4b7DRC explicitly disable subsampling as follows: 10985996a25e2f50d20d6a8f09830724035b49c3927bGuido Vollbeding 1099b775351012af176720429ac21d11682a0b75b4b7DRC cinfo->comp_info[0].v_samp_factor = 1; 1100b775351012af176720429ac21d11682a0b75b4b7DRC cinfo->comp_info[0].h_samp_factor = 1; 11015996a25e2f50d20d6a8f09830724035b49c3927bGuido Vollbeding 11026eb7d3798b5a79347c62825fc4c16f7ce673bdd0Alex NaidisJHUFF_TBL *dc_huff_tbl_ptrs[NUM_HUFF_TBLS] 11036eb7d3798b5a79347c62825fc4c16f7ce673bdd0Alex NaidisJHUFF_TBL *ac_huff_tbl_ptrs[NUM_HUFF_TBLS] 1104b775351012af176720429ac21d11682a0b75b4b7DRC Pointers to Huffman coding tables, one per table slot, or NULL if 1105b775351012af176720429ac21d11682a0b75b4b7DRC no table is defined for a slot. Slots 0 and 1 are filled with the 1106b775351012af176720429ac21d11682a0b75b4b7DRC JPEG sample tables by jpeg_set_defaults(). If you need to allocate 1107b775351012af176720429ac21d11682a0b75b4b7DRC more table structures, jpeg_alloc_huff_table() may be used. 1108b775351012af176720429ac21d11682a0b75b4b7DRC Note that optimal Huffman tables can be computed for an image 1109b775351012af176720429ac21d11682a0b75b4b7DRC by setting optimize_coding, as discussed above; there's seldom 1110b775351012af176720429ac21d11682a0b75b4b7DRC any need to mess with providing your own Huffman tables. 111136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 11125996a25e2f50d20d6a8f09830724035b49c3927bGuido Vollbeding 111330913542c01cf6bb4a6b479e56d87e7a8eb048fbDRC[libjpeg v7+ API/ABI emulation only] 111430913542c01cf6bb4a6b479e56d87e7a8eb048fbDRCThe actual dimensions of the JPEG image that will be written to the file are 111530913542c01cf6bb4a6b479e56d87e7a8eb048fbDRCgiven by the following fields. These are computed from the input image 111630913542c01cf6bb4a6b479e56d87e7a8eb048fbDRCdimensions and the compression parameters by jpeg_start_compress(). You can 111730913542c01cf6bb4a6b479e56d87e7a8eb048fbDRCalso call jpeg_calc_jpeg_dimensions() to obtain the values that will result 11185996a25e2f50d20d6a8f09830724035b49c3927bGuido Vollbedingfrom the current parameter settings. This can be useful if you are trying 11195996a25e2f50d20d6a8f09830724035b49c3927bGuido Vollbedingto pick a scaling ratio that will get close to a desired target size. 11205996a25e2f50d20d6a8f09830724035b49c3927bGuido Vollbeding 1121b775351012af176720429ac21d11682a0b75b4b7DRCJDIMENSION jpeg_width Actual dimensions of output image. 11225996a25e2f50d20d6a8f09830724035b49c3927bGuido VollbedingJDIMENSION jpeg_height 112336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 112436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 112536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LanePer-component parameters are stored in the struct cinfo.comp_info[i] for 112636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecomponent number i. Note that components here refer to components of the 112736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJPEG color space, *not* the source image color space. A suitably large 112836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecomp_info[] array is allocated by jpeg_set_defaults(); if you choose not 112936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneto use that routine, it's up to you to allocate the array. 113036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 113136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneint component_id 1132b775351012af176720429ac21d11682a0b75b4b7DRC The one-byte identifier code to be recorded in the JPEG file for 1133b775351012af176720429ac21d11682a0b75b4b7DRC this component. For the standard color spaces, we recommend you 1134b775351012af176720429ac21d11682a0b75b4b7DRC leave the default values alone. 113536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 113636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneint h_samp_factor 113736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneint v_samp_factor 1138b775351012af176720429ac21d11682a0b75b4b7DRC Horizontal and vertical sampling factors for the component; must 1139b775351012af176720429ac21d11682a0b75b4b7DRC be 1..4 according to the JPEG standard. Note that larger sampling 1140b775351012af176720429ac21d11682a0b75b4b7DRC factors indicate a higher-resolution component; many people find 1141b775351012af176720429ac21d11682a0b75b4b7DRC this behavior quite unintuitive. The default values are 2,2 for 1142b775351012af176720429ac21d11682a0b75b4b7DRC luminance components and 1,1 for chrominance components, except 1143b775351012af176720429ac21d11682a0b75b4b7DRC for grayscale where 1,1 is used. 114436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 114536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneint quant_tbl_no 1146b775351012af176720429ac21d11682a0b75b4b7DRC Quantization table number for component. The default value is 1147b775351012af176720429ac21d11682a0b75b4b7DRC 0 for luminance components and 1 for chrominance components. 114836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 114936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneint dc_tbl_no 115036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneint ac_tbl_no 1151b775351012af176720429ac21d11682a0b75b4b7DRC DC and AC entropy coding table numbers. The default values are 1152b775351012af176720429ac21d11682a0b75b4b7DRC 0 for luminance components and 1 for chrominance components. 115336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 115436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneint component_index 1155b775351012af176720429ac21d11682a0b75b4b7DRC Must equal the component's index in comp_info[]. (Beginning in 1156b775351012af176720429ac21d11682a0b75b4b7DRC release v6, the compressor library will fill this in automatically; 1157b775351012af176720429ac21d11682a0b75b4b7DRC you don't have to.) 115836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 115936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 116036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneDecompression parameter selection 116136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane--------------------------------- 116236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 116336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneDecompression parameter selection is somewhat simpler than compression 116436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneparameter selection, since all of the JPEG internal parameters are 116536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanerecorded in the source file and need not be supplied by the application. 116636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane(Unless you are working with abbreviated files, in which case see 116736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane"Abbreviated datastreams", below.) Decompression parameters control 116836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe postprocessing done on the image to deliver it in a format suitable 116936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefor the application's use. Many of the parameters control speed/quality 117036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanetradeoffs, in which faster decompression may be obtained at the price of 117136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanea poorer-quality image. The defaults select the highest quality (slowest) 117236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneprocessing. 117336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 117436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe following fields in the JPEG object are set by jpeg_read_header() and 117536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemay be useful to the application in choosing decompression parameters: 117636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 1177b775351012af176720429ac21d11682a0b75b4b7DRCJDIMENSION image_width Width and height of image 117836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJDIMENSION image_height 1179b775351012af176720429ac21d11682a0b75b4b7DRCint num_components Number of color components 1180b775351012af176720429ac21d11682a0b75b4b7DRCJ_COLOR_SPACE jpeg_color_space Colorspace of image 1181b775351012af176720429ac21d11682a0b75b4b7DRCboolean saw_JFIF_marker TRUE if a JFIF APP0 marker was seen 1182b775351012af176720429ac21d11682a0b75b4b7DRC UINT8 JFIF_major_version Version information from JFIF marker 11835ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane UINT8 JFIF_minor_version 1184b775351012af176720429ac21d11682a0b75b4b7DRC UINT8 density_unit Resolution data from JFIF marker 118536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane UINT16 X_density 118636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane UINT16 Y_density 1187b775351012af176720429ac21d11682a0b75b4b7DRCboolean saw_Adobe_marker TRUE if an Adobe APP14 marker was seen 1188b775351012af176720429ac21d11682a0b75b4b7DRC UINT8 Adobe_transform Color transform code from Adobe marker 118936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 119036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe JPEG color space, unfortunately, is something of a guess since the JPEG 119136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanestandard proper does not provide a way to record it. In practice most files 119236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneadhere to the JFIF or Adobe conventions, and the decoder will recognize these 119336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecorrectly. See "Special color spaces", below, for more info. 119436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 119536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 119636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe decompression parameters that determine the basic properties of the 119736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanereturned image are: 119836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 119936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJ_COLOR_SPACE out_color_space 1200b775351012af176720429ac21d11682a0b75b4b7DRC Output color space. jpeg_read_header() sets an appropriate default 1201b775351012af176720429ac21d11682a0b75b4b7DRC based on jpeg_color_space; typically it will be RGB or grayscale. 1202b775351012af176720429ac21d11682a0b75b4b7DRC The application can change this field to request output in a different 1203b775351012af176720429ac21d11682a0b75b4b7DRC colorspace. For example, set it to JCS_GRAYSCALE to get grayscale 1204b775351012af176720429ac21d11682a0b75b4b7DRC output from a color file. (This is useful for previewing: grayscale 1205b775351012af176720429ac21d11682a0b75b4b7DRC output is faster than full color since the color components need not 1206b775351012af176720429ac21d11682a0b75b4b7DRC be processed.) Note that not all possible color space transforms are 1207b775351012af176720429ac21d11682a0b75b4b7DRC currently implemented; you may need to extend jdcolor.c if you want an 1208b775351012af176720429ac21d11682a0b75b4b7DRC unusual conversion. 120936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 121036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneunsigned int scale_num, scale_denom 1211b775351012af176720429ac21d11682a0b75b4b7DRC Scale the image by the fraction scale_num/scale_denom. Default is 1212b775351012af176720429ac21d11682a0b75b4b7DRC 1/1, or no scaling. Currently, the only supported scaling ratios 1213b775351012af176720429ac21d11682a0b75b4b7DRC are M/8 with all M from 1 to 16, or any reduced fraction thereof (such 1214b775351012af176720429ac21d11682a0b75b4b7DRC as 1/2, 3/4, etc.) (The library design allows for arbitrary 1215b775351012af176720429ac21d11682a0b75b4b7DRC scaling ratios but this is not likely to be implemented any time soon.) 1216b775351012af176720429ac21d11682a0b75b4b7DRC Smaller scaling ratios permit significantly faster decoding since 1217b775351012af176720429ac21d11682a0b75b4b7DRC fewer pixels need be processed and a simpler IDCT method can be used. 121836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 121936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneboolean quantize_colors 1220b775351012af176720429ac21d11682a0b75b4b7DRC If set TRUE, colormapped output will be delivered. Default is FALSE, 1221b775351012af176720429ac21d11682a0b75b4b7DRC meaning that full-color output will be delivered. 122236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 122336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe next three parameters are relevant only if quantize_colors is TRUE. 122436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 122536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneint desired_number_of_colors 1226b775351012af176720429ac21d11682a0b75b4b7DRC Maximum number of colors to use in generating a library-supplied color 1227b775351012af176720429ac21d11682a0b75b4b7DRC map (the actual number of colors is returned in a different field). 1228b775351012af176720429ac21d11682a0b75b4b7DRC Default 256. Ignored when the application supplies its own color map. 122936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 123036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneboolean two_pass_quantize 1231b775351012af176720429ac21d11682a0b75b4b7DRC If TRUE, an extra pass over the image is made to select a custom color 1232b775351012af176720429ac21d11682a0b75b4b7DRC map for the image. This usually looks a lot better than the one-size- 1233b775351012af176720429ac21d11682a0b75b4b7DRC fits-all colormap that is used otherwise. Default is TRUE. Ignored 1234b775351012af176720429ac21d11682a0b75b4b7DRC when the application supplies its own color map. 123536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 123636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJ_DITHER_MODE dither_mode 1237b775351012af176720429ac21d11682a0b75b4b7DRC Selects color dithering method. Supported values are: 1238b775351012af176720429ac21d11682a0b75b4b7DRC JDITHER_NONE no dithering: fast, very low quality 1239b775351012af176720429ac21d11682a0b75b4b7DRC JDITHER_ORDERED ordered dither: moderate speed and quality 1240b775351012af176720429ac21d11682a0b75b4b7DRC JDITHER_FS Floyd-Steinberg dither: slow, high quality 1241b775351012af176720429ac21d11682a0b75b4b7DRC Default is JDITHER_FS. (At present, ordered dither is implemented 1242b775351012af176720429ac21d11682a0b75b4b7DRC only in the single-pass, standard-colormap case. If you ask for 1243b775351012af176720429ac21d11682a0b75b4b7DRC ordered dither when two_pass_quantize is TRUE or when you supply 1244b775351012af176720429ac21d11682a0b75b4b7DRC an external color map, you'll get F-S dithering.) 124536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 124636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneWhen quantize_colors is TRUE, the target color map is described by the next 124736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanetwo fields. colormap is set to NULL by jpeg_read_header(). The application 124836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecan supply a color map by setting colormap non-NULL and setting 124936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneactual_number_of_colors to the map size. Otherwise, jpeg_start_decompress() 125036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneselects a suitable color map and sets these two fields itself. 125136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane[Implementation restriction: at present, an externally supplied colormap is 125236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneonly accepted for 3-component output color spaces.] 125336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 125436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJSAMPARRAY colormap 1255b775351012af176720429ac21d11682a0b75b4b7DRC The color map, represented as a 2-D pixel array of out_color_components 1256b775351012af176720429ac21d11682a0b75b4b7DRC rows and actual_number_of_colors columns. Ignored if not quantizing. 1257b775351012af176720429ac21d11682a0b75b4b7DRC CAUTION: if the JPEG library creates its own colormap, the storage 1258b775351012af176720429ac21d11682a0b75b4b7DRC pointed to by this field is released by jpeg_finish_decompress(). 1259b775351012af176720429ac21d11682a0b75b4b7DRC Copy the colormap somewhere else first, if you want to save it. 126036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 126136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneint actual_number_of_colors 1262b775351012af176720429ac21d11682a0b75b4b7DRC The number of colors in the color map. 126336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 126436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAdditional decompression parameters that the application may set include: 126536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 126636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJ_DCT_METHOD dct_method 12678940e6ca8628e10b45486fad4572a15b63546eb1DRC Selects the algorithm used for the DCT step. Choices are: 12688940e6ca8628e10b45486fad4572a15b63546eb1DRC JDCT_ISLOW: slow but accurate integer algorithm 12698940e6ca8628e10b45486fad4572a15b63546eb1DRC JDCT_IFAST: faster, less accurate integer method 12708940e6ca8628e10b45486fad4572a15b63546eb1DRC JDCT_FLOAT: floating-point method 12718940e6ca8628e10b45486fad4572a15b63546eb1DRC JDCT_DEFAULT: default method (normally JDCT_ISLOW) 12728940e6ca8628e10b45486fad4572a15b63546eb1DRC JDCT_FASTEST: fastest method (normally JDCT_IFAST) 12738940e6ca8628e10b45486fad4572a15b63546eb1DRC In libjpeg-turbo, JDCT_IFAST is generally about 5-15% faster than 12748940e6ca8628e10b45486fad4572a15b63546eb1DRC JDCT_ISLOW when using the x86/x86-64 SIMD extensions (results may vary 12758940e6ca8628e10b45486fad4572a15b63546eb1DRC with other SIMD implementations, or when using libjpeg-turbo without 12768940e6ca8628e10b45486fad4572a15b63546eb1DRC SIMD extensions.) If the JPEG image was compressed using a quality 12778940e6ca8628e10b45486fad4572a15b63546eb1DRC level of 85 or below, then there should be little or no perceptible 12788940e6ca8628e10b45486fad4572a15b63546eb1DRC difference between the two algorithms. When decompressing images that 12798940e6ca8628e10b45486fad4572a15b63546eb1DRC were compressed using quality levels above 85, however, the difference 12808940e6ca8628e10b45486fad4572a15b63546eb1DRC between JDCT_IFAST and JDCT_ISLOW becomes more pronounced. With images 12818940e6ca8628e10b45486fad4572a15b63546eb1DRC compressed using quality=97, for instance, JDCT_IFAST incurs generally 12828940e6ca8628e10b45486fad4572a15b63546eb1DRC about a 4-6 dB loss (in PSNR) relative to JDCT_ISLOW, but this can be 12838940e6ca8628e10b45486fad4572a15b63546eb1DRC larger for some images. If you can avoid it, do not use JDCT_IFAST 12848940e6ca8628e10b45486fad4572a15b63546eb1DRC when decompressing images that were compressed using quality levels 12858940e6ca8628e10b45486fad4572a15b63546eb1DRC above 97. The algorithm often degenerates for such images and can 12868940e6ca8628e10b45486fad4572a15b63546eb1DRC actually produce a more lossy output image than if the JPEG image had 128705524e671e42b8a4ba6d0cfab1ffb1af20a29919DRC been compressed using lower quality levels. JDCT_FLOAT is mainly a 12888940e6ca8628e10b45486fad4572a15b63546eb1DRC legacy feature. It does not produce significantly more accurate 12898940e6ca8628e10b45486fad4572a15b63546eb1DRC results than the ISLOW method, and it is much slower. The FLOAT method 12908940e6ca8628e10b45486fad4572a15b63546eb1DRC may also give different results on different machines due to varying 12918940e6ca8628e10b45486fad4572a15b63546eb1DRC roundoff behavior, whereas the integer methods should give the same 12928940e6ca8628e10b45486fad4572a15b63546eb1DRC results on all machines. 129336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 129436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneboolean do_fancy_upsampling 1295b775351012af176720429ac21d11682a0b75b4b7DRC If TRUE, do careful upsampling of chroma components. If FALSE, 1296b775351012af176720429ac21d11682a0b75b4b7DRC a faster but sloppier method is used. Default is TRUE. The visual 1297b775351012af176720429ac21d11682a0b75b4b7DRC impact of the sloppier method is often very small. 129836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 1299bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneboolean do_block_smoothing 1300b775351012af176720429ac21d11682a0b75b4b7DRC If TRUE, interblock smoothing is applied in early stages of decoding 1301b775351012af176720429ac21d11682a0b75b4b7DRC progressive JPEG files; if FALSE, not. Default is TRUE. Early 1302b775351012af176720429ac21d11682a0b75b4b7DRC progression stages look "fuzzy" with smoothing, "blocky" without. 1303b775351012af176720429ac21d11682a0b75b4b7DRC In any case, block smoothing ceases to be applied after the first few 1304b775351012af176720429ac21d11682a0b75b4b7DRC AC coefficients are known to full accuracy, so it is relevant only 1305b775351012af176720429ac21d11682a0b75b4b7DRC when using buffered-image mode for progressive images. 1306bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1307bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneboolean enable_1pass_quant 1308bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneboolean enable_external_quant 1309bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneboolean enable_2pass_quant 1310b775351012af176720429ac21d11682a0b75b4b7DRC These are significant only in buffered-image mode, which is 1311b775351012af176720429ac21d11682a0b75b4b7DRC described in its own section below. 1312bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 131336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 131436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe output image dimensions are given by the following fields. These are 131536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecomputed from the source image dimensions and the decompression parameters 131636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneby jpeg_start_decompress(). You can also call jpeg_calc_output_dimensions() 131736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneto obtain the values that will result from the current parameter settings. 131836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThis can be useful if you are trying to pick a scaling ratio that will get 131936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneclose to a desired target size. It's also important if you are using the 132036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJPEG library's memory manager to allocate output buffer space, because you 132136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneare supposed to request such buffers *before* jpeg_start_decompress(). 132236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 1323b775351012af176720429ac21d11682a0b75b4b7DRCJDIMENSION output_width Actual dimensions of output image. 132436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJDIMENSION output_height 1325b775351012af176720429ac21d11682a0b75b4b7DRCint out_color_components Number of color components in out_color_space. 1326b775351012af176720429ac21d11682a0b75b4b7DRCint output_components Number of color components returned. 1327b775351012af176720429ac21d11682a0b75b4b7DRCint rec_outbuf_height Recommended height of scanline buffer. 132836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 132936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneWhen quantizing colors, output_components is 1, indicating a single color map 133036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneindex per pixel. Otherwise it equals out_color_components. The output arrays 133136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneare required to be output_width * output_components JSAMPLEs wide. 133236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 133336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanerec_outbuf_height is the recommended minimum height (in scanlines) of the 133436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanebuffer passed to jpeg_read_scanlines(). If the buffer is smaller, the 133536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanelibrary will still work, but time will be wasted due to unnecessary data 133636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecopying. In high-quality modes, rec_outbuf_height is always 1, but some 133736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefaster, lower-quality modes set it to larger values (typically 2 to 4). 133836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf you are going to ask for a high-speed processing mode, you may as well 133936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanego to the trouble of honoring rec_outbuf_height so as to avoid data copying. 13405ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane(An output buffer larger than rec_outbuf_height lines is OK, but won't 13415ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneprovide any material speed improvement over that height.) 134236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 134336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 134436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneSpecial color spaces 134536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane-------------------- 134636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 134736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe JPEG standard itself is "color blind" and doesn't specify any particular 134836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecolor space. It is customary to convert color data to a luminance/chrominance 134936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecolor space before compressing, since this permits greater compression. The 135036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneexisting de-facto JPEG file format standards specify YCbCr or grayscale data 135136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane(JFIF), or grayscale, RGB, YCbCr, CMYK, or YCCK (Adobe). For special 135236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneapplications such as multispectral images, other color spaces can be used, 135336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanebut it must be understood that such files will be unportable. 135436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 135536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe JPEG library can handle the most common colorspace conversions (namely 135636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneRGB <=> YCbCr and CMYK <=> YCCK). It can also deal with data of an unknown 135736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecolor space, passing it through without conversion. If you deal extensively 135836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewith an unusual color space, you can easily extend the library to understand 135936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneadditional color spaces and perform appropriate conversions. 136036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 136136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneFor compression, the source data's color space is specified by field 136236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanein_color_space. This is transformed to the JPEG file's color space given 136336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneby jpeg_color_space. jpeg_set_defaults() chooses a reasonable JPEG color 136436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanespace depending on in_color_space, but you can override this by calling 136536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_set_colorspace(). Of course you must select a supported transformation. 136636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejccolor.c currently supports the following transformations: 1367b775351012af176720429ac21d11682a0b75b4b7DRC RGB => YCbCr 1368b775351012af176720429ac21d11682a0b75b4b7DRC RGB => GRAYSCALE 1369b775351012af176720429ac21d11682a0b75b4b7DRC YCbCr => GRAYSCALE 1370b775351012af176720429ac21d11682a0b75b4b7DRC CMYK => YCCK 137136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneplus the null transforms: GRAYSCALE => GRAYSCALE, RGB => RGB, 137236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYCbCr => YCbCr, CMYK => CMYK, YCCK => YCCK, and UNKNOWN => UNKNOWN. 137336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 137436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe de-facto file format standards (JFIF and Adobe) specify APPn markers that 137536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneindicate the color space of the JPEG file. It is important to ensure that 137636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethese are written correctly, or omitted if the JPEG file's color space is not 137736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneone of the ones supported by the de-facto standards. jpeg_set_colorspace() 137836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewill set the compression parameters to include or omit the APPn markers 137936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneproperly, so long as it is told the truth about the JPEG color space. 138036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneFor example, if you are writing some random 3-component color space without 138136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneconversion, don't try to fake out the library by setting in_color_space and 138236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_color_space to JCS_YCbCr; use JCS_UNKNOWN. You may want to write an 138336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAPPn marker of your own devising to identify the colorspace --- see "Special 138436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemarkers", below. 138536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 138636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneWhen told that the color space is UNKNOWN, the library will default to using 138736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneluminance-quality compression parameters for all color components. You may 138836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewell want to change these parameters. See the source code for 138936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_set_colorspace(), in jcparam.c, for details. 139036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 139136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneFor decompression, the JPEG file's color space is given in jpeg_color_space, 139236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneand this is transformed to the output color space out_color_space. 139336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_read_header's setting of jpeg_color_space can be relied on if the file 139436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneconforms to JFIF or Adobe conventions, but otherwise it is no better than a 139536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneguess. If you know the JPEG file's color space for certain, you can override 139636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_read_header's guess by setting jpeg_color_space. jpeg_read_header also 139736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneselects a default output color space based on (its guess of) jpeg_color_space; 139836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneset out_color_space to override this. Again, you must select a supported 139936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanetransformation. jdcolor.c currently supports 1400b775351012af176720429ac21d11682a0b75b4b7DRC YCbCr => RGB 1401b775351012af176720429ac21d11682a0b75b4b7DRC YCbCr => GRAYSCALE 1402b775351012af176720429ac21d11682a0b75b4b7DRC RGB => GRAYSCALE 1403b775351012af176720429ac21d11682a0b75b4b7DRC GRAYSCALE => RGB 1404b775351012af176720429ac21d11682a0b75b4b7DRC YCCK => CMYK 14055ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneas well as the null transforms. (Since GRAYSCALE=>RGB is provided, an 14065ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneapplication can force grayscale JPEGs to look like color JPEGs if it only 14075ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanewants to handle one case.) 140836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 140936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe two-pass color quantizer, jquant2.c, is specialized to handle RGB data 141036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane(it weights distances appropriately for RGB colors). You'll need to modify 141136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe code if you want to use it for non-RGB output color spaces. Note that 141236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejquant2.c is used to map to an application-supplied colormap as well as for 141336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe normal two-pass colormap selection process. 141436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 141536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneCAUTION: it appears that Adobe Photoshop writes inverted data in CMYK JPEG 141636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefiles: 0 represents 100% ink coverage, rather than 0% ink as you'd expect. 141736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThis is arguably a bug in Photoshop, but if you need to work with Photoshop 141836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneCMYK files, you will have to deal with it in your application. We cannot 141936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane"fix" this in the library by inverting the data during the CMYK<=>YCCK 142036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanetransform, because that would break other applications, notably Ghostscript. 142136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LanePhotoshop versions prior to 3.0 write EPS files containing JPEG-encoded CMYK 142236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedata in the same inverted-YCCK representation used in bare JPEG files, but 142336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe surrounding PostScript code performs an inversion using the PS image 142436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneoperator. I am told that Photoshop 3.0 will write uninverted YCCK in 142536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneEPS/JPEG files, and will omit the PS-level inversion. (But the data 142636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanepolarity used in bare JPEG files will not change in 3.0.) In either case, 142736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe JPEG library must not invert the data itself, or else Ghostscript would 142836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneread these EPS files incorrectly. 142936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 143036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 143136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneError handling 143236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane-------------- 143336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 143436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneWhen the default error handler is used, any error detected inside the JPEG 143536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneroutines will cause a message to be printed on stderr, followed by exit(). 143636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou can supply your own error handling routines to override this behavior 143736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneand to control the treatment of nonfatal warnings and trace/debug messages. 143836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe file example.c illustrates the most common case, which is to have the 143936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneapplication regain control after an error rather than exiting. 144036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 144136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe JPEG library never writes any message directly; it always goes through 144236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe error handling routines. Three classes of messages are recognized: 144336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * Fatal errors: the library cannot continue. 144436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * Warnings: the library can continue, but the data is corrupt, and a 144536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane damaged output image is likely to result. 144636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * Trace/informational messages. These come with a trace level indicating 144736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane the importance of the message; you can control the verbosity of the 144836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane program by adjusting the maximum trace level that will be displayed. 144936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 145036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou may, if you wish, simply replace the entire JPEG error handling module 145136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane(jerror.c) with your own code. However, you can avoid code duplication by 145236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneonly replacing some of the routines depending on the behavior you need. 145336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThis is accomplished by calling jpeg_std_error() as usual, but then overriding 145436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesome of the method pointers in the jpeg_error_mgr struct, as illustrated by 145536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneexample.c. 145636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 145736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAll of the error handling routines will receive a pointer to the JPEG object 145836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane(a j_common_ptr which points to either a jpeg_compress_struct or a 145936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_decompress_struct; if you need to tell which, test the is_decompressor 146036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefield). This struct includes a pointer to the error manager struct in its 146136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane"err" field. Frequently, custom error handler routines will need to access 146236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneadditional data which is not known to the JPEG library or the standard error 146336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanehandler. The most convenient way to do this is to embed either the JPEG 146436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneobject or the jpeg_error_mgr struct in a larger structure that contains 146536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneadditional fields; then casting the passed pointer provides access to the 14665ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneadditional fields. Again, see example.c for one way to do it. (Beginning 14675ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanewith IJG version 6b, there is also a void pointer "client_data" in each 14685ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneJPEG object, which the application can also use to find related data. 14695ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneThe library does not touch client_data at all.) 147036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 147136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe individual methods that you might wish to override are: 147236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 147336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneerror_exit (j_common_ptr cinfo) 1474b775351012af176720429ac21d11682a0b75b4b7DRC Receives control for a fatal error. Information sufficient to 1475b775351012af176720429ac21d11682a0b75b4b7DRC generate the error message has been stored in cinfo->err; call 1476b775351012af176720429ac21d11682a0b75b4b7DRC output_message to display it. Control must NOT return to the caller; 1477b775351012af176720429ac21d11682a0b75b4b7DRC generally this routine will exit() or longjmp() somewhere. 1478b775351012af176720429ac21d11682a0b75b4b7DRC Typically you would override this routine to get rid of the exit() 1479b775351012af176720429ac21d11682a0b75b4b7DRC default behavior. Note that if you continue processing, you should 1480b775351012af176720429ac21d11682a0b75b4b7DRC clean up the JPEG object with jpeg_abort() or jpeg_destroy(). 148136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 148236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneoutput_message (j_common_ptr cinfo) 1483b775351012af176720429ac21d11682a0b75b4b7DRC Actual output of any JPEG message. Override this to send messages 1484b775351012af176720429ac21d11682a0b75b4b7DRC somewhere other than stderr. Note that this method does not know 1485b775351012af176720429ac21d11682a0b75b4b7DRC how to generate a message, only where to send it. 148636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 14876eb7d3798b5a79347c62825fc4c16f7ce673bdd0Alex Naidisformat_message (j_common_ptr cinfo, char *buffer) 1488b775351012af176720429ac21d11682a0b75b4b7DRC Constructs a readable error message string based on the error info 1489b775351012af176720429ac21d11682a0b75b4b7DRC stored in cinfo->err. This method is called by output_message. Few 1490b775351012af176720429ac21d11682a0b75b4b7DRC applications should need to override this method. One possible 1491b775351012af176720429ac21d11682a0b75b4b7DRC reason for doing so is to implement dynamic switching of error message 1492b775351012af176720429ac21d11682a0b75b4b7DRC language. 149336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 149436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneemit_message (j_common_ptr cinfo, int msg_level) 1495b775351012af176720429ac21d11682a0b75b4b7DRC Decide whether or not to emit a warning or trace message; if so, 1496b775351012af176720429ac21d11682a0b75b4b7DRC calls output_message. The main reason for overriding this method 1497b775351012af176720429ac21d11682a0b75b4b7DRC would be to abort on warnings. msg_level is -1 for warnings, 1498b775351012af176720429ac21d11682a0b75b4b7DRC 0 and up for trace messages. 149936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 150036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneOnly error_exit() and emit_message() are called from the rest of the JPEG 150136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanelibrary; the other two are internal to the error handler. 150236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 150336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe actual message texts are stored in an array of strings which is pointed to 150436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneby the field err->jpeg_message_table. The messages are numbered from 0 to 150536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneerr->last_jpeg_message, and it is these code numbers that are used in the 150636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJPEG library code. You could replace the message texts (for instance, with 150736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemessages in French or German) by changing the message table pointer. See 150836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejerror.h for the default texts. CAUTION: this table will almost certainly 150936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanechange or grow from one library version to the next. 151036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 151136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIt may be useful for an application to add its own message texts that are 151236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanehandled by the same mechanism. The error handler supports a second "add-on" 151336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemessage table for this purpose. To define an addon table, set the pointer 151436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneerr->addon_message_table and the message numbers err->first_addon_message and 151536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneerr->last_addon_message. If you number the addon messages beginning at 1000 151636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneor so, you won't have to worry about conflicts with the library's built-in 151736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemessages. See the sample applications cjpeg/djpeg for an example of using 151836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneaddon messages (the addon messages are defined in cderror.h). 151936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 152036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneActual invocation of the error handler is done via macros defined in jerror.h: 1521b775351012af176720429ac21d11682a0b75b4b7DRC ERREXITn(...) for fatal errors 1522b775351012af176720429ac21d11682a0b75b4b7DRC WARNMSn(...) for corrupt-data warnings 1523b775351012af176720429ac21d11682a0b75b4b7DRC TRACEMSn(...) for trace and informational messages. 152436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThese macros store the message code and any additional parameters into the 152536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneerror handler struct, then invoke the error_exit() or emit_message() method. 152636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe variants of each macro are for varying numbers of additional parameters. 152736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe additional parameters are inserted into the generated message using 152836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanestandard printf() format codes. 152936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 153036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneSee jerror.h and jerror.c for further details. 153136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 153236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 153336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneCompressed data handling (source and destination managers) 153436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane---------------------------------------------------------- 153536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 153636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe JPEG compression library sends its compressed data to a "destination 153736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemanager" module. The default destination manager just writes the data to a 1538989630f70cf1af69ebfefca8910d1647bf189712Guido Vollbedingmemory buffer or to a stdio stream, but you can provide your own manager to 1539989630f70cf1af69ebfefca8910d1647bf189712Guido Vollbedingdo something else. Similarly, the decompression library calls a "source 1540989630f70cf1af69ebfefca8910d1647bf189712Guido Vollbedingmanager" to obtain the compressed data; you can provide your own source 1541989630f70cf1af69ebfefca8910d1647bf189712Guido Vollbedingmanager if you want the data to come from somewhere other than a memory 1542989630f70cf1af69ebfefca8910d1647bf189712Guido Vollbedingbuffer or a stdio stream. 154336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 154436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIn both cases, compressed data is processed a bufferload at a time: the 154536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedestination or source manager provides a work buffer, and the library invokes 154636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe manager only when the buffer is filled or emptied. (You could define a 154736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneone-character buffer to force the manager to be invoked for each byte, but 154836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethat would be rather inefficient.) The buffer's size and location are 1549989630f70cf1af69ebfefca8910d1647bf189712Guido Vollbedingcontrolled by the manager, not by the library. For example, the memory 1550989630f70cf1af69ebfefca8910d1647bf189712Guido Vollbedingsource manager just makes the buffer pointer and length point to the original 1551989630f70cf1af69ebfefca8910d1647bf189712Guido Vollbedingdata in memory. In this case the buffer-reload procedure will be invoked 1552989630f70cf1af69ebfefca8910d1647bf189712Guido Vollbedingonly if the decompressor ran off the end of the datastream, which would 1553989630f70cf1af69ebfefca8910d1647bf189712Guido Vollbedingindicate an erroneous datastream. 155436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 155536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe work buffer is defined as an array of datatype JOCTET, which is generally 155636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane"char" or "unsigned char". On a machine where char is not exactly 8 bits 155736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewide, you must define JOCTET as a wider data type and then modify the data 155836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesource and destination modules to transcribe the work arrays into 8-bit units 155936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneon external storage. 156036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 156136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneA data destination manager struct contains a pointer and count defining the 156236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanenext byte to write in the work buffer and the remaining free space: 156336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 15646eb7d3798b5a79347c62825fc4c16f7ce673bdd0Alex Naidis JOCTET *next_output_byte; /* => next byte to write in buffer */ 1565b775351012af176720429ac21d11682a0b75b4b7DRC size_t free_in_buffer; /* # of byte spaces remaining in buffer */ 156636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 156736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe library increments the pointer and decrements the count until the buffer 156836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneis filled. The manager's empty_output_buffer method must reset the pointer 156936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneand count. The manager is expected to remember the buffer's starting address 157036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneand total size in private fields not visible to the library. 157136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 157236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneA data destination manager provides three methods: 157336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 157436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneinit_destination (j_compress_ptr cinfo) 1575b775351012af176720429ac21d11682a0b75b4b7DRC Initialize destination. This is called by jpeg_start_compress() 1576b775351012af176720429ac21d11682a0b75b4b7DRC before any data is actually written. It must initialize 1577b775351012af176720429ac21d11682a0b75b4b7DRC next_output_byte and free_in_buffer. free_in_buffer must be 1578b775351012af176720429ac21d11682a0b75b4b7DRC initialized to a positive value. 157936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 158036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneempty_output_buffer (j_compress_ptr cinfo) 1581b775351012af176720429ac21d11682a0b75b4b7DRC This is called whenever the buffer has filled (free_in_buffer 1582b775351012af176720429ac21d11682a0b75b4b7DRC reaches zero). In typical applications, it should write out the 1583b775351012af176720429ac21d11682a0b75b4b7DRC *entire* buffer (use the saved start address and buffer length; 1584b775351012af176720429ac21d11682a0b75b4b7DRC ignore the current state of next_output_byte and free_in_buffer). 1585b775351012af176720429ac21d11682a0b75b4b7DRC Then reset the pointer & count to the start of the buffer, and 1586b775351012af176720429ac21d11682a0b75b4b7DRC return TRUE indicating that the buffer has been dumped. 1587b775351012af176720429ac21d11682a0b75b4b7DRC free_in_buffer must be set to a positive value when TRUE is 1588b775351012af176720429ac21d11682a0b75b4b7DRC returned. A FALSE return should only be used when I/O suspension is 1589b775351012af176720429ac21d11682a0b75b4b7DRC desired (this operating mode is discussed in the next section). 159036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 159136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneterm_destination (j_compress_ptr cinfo) 1592b775351012af176720429ac21d11682a0b75b4b7DRC Terminate destination --- called by jpeg_finish_compress() after all 1593b775351012af176720429ac21d11682a0b75b4b7DRC data has been written. In most applications, this must flush any 1594b775351012af176720429ac21d11682a0b75b4b7DRC data remaining in the buffer. Use either next_output_byte or 1595b775351012af176720429ac21d11682a0b75b4b7DRC free_in_buffer to determine how much data is in the buffer. 159636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 159736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneterm_destination() is NOT called by jpeg_abort() or jpeg_destroy(). If you 159836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewant the destination manager to be cleaned up during an abort, you must do it 159936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneyourself. 160036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 160136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou will also need code to create a jpeg_destination_mgr struct, fill in its 160236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemethod pointers, and insert a pointer to the struct into the "dest" field of 160336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe JPEG compression object. This can be done in-line in your setup code if 160436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneyou like, but it's probably cleaner to provide a separate routine similar to 1605989630f70cf1af69ebfefca8910d1647bf189712Guido Vollbedingthe jpeg_stdio_dest() or jpeg_mem_dest() routines of the supplied destination 1606989630f70cf1af69ebfefca8910d1647bf189712Guido Vollbedingmanagers. 160736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 160836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneDecompression source managers follow a parallel design, but with some 160936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneadditional frammishes. The source manager struct contains a pointer and count 161036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedefining the next byte to read from the work buffer and the number of bytes 161136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneremaining: 161236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 16136eb7d3798b5a79347c62825fc4c16f7ce673bdd0Alex Naidis const JOCTET *next_input_byte; /* => next byte to read from buffer */ 1614b775351012af176720429ac21d11682a0b75b4b7DRC size_t bytes_in_buffer; /* # of bytes remaining in buffer */ 161536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 161636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe library increments the pointer and decrements the count until the buffer 161736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneis emptied. The manager's fill_input_buffer method must reset the pointer and 161836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecount. In most applications, the manager must remember the buffer's starting 161936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneaddress and total size in private fields not visible to the library. 162036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 162136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneA data source manager provides five methods: 162236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 162336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneinit_source (j_decompress_ptr cinfo) 1624b775351012af176720429ac21d11682a0b75b4b7DRC Initialize source. This is called by jpeg_read_header() before any 1625b775351012af176720429ac21d11682a0b75b4b7DRC data is actually read. Unlike init_destination(), it may leave 1626b775351012af176720429ac21d11682a0b75b4b7DRC bytes_in_buffer set to 0 (in which case a fill_input_buffer() call 1627b775351012af176720429ac21d11682a0b75b4b7DRC will occur immediately). 162836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 162936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefill_input_buffer (j_decompress_ptr cinfo) 1630b775351012af176720429ac21d11682a0b75b4b7DRC This is called whenever bytes_in_buffer has reached zero and more 1631b775351012af176720429ac21d11682a0b75b4b7DRC data is wanted. In typical applications, it should read fresh data 1632b775351012af176720429ac21d11682a0b75b4b7DRC into the buffer (ignoring the current state of next_input_byte and 1633b775351012af176720429ac21d11682a0b75b4b7DRC bytes_in_buffer), reset the pointer & count to the start of the 1634b775351012af176720429ac21d11682a0b75b4b7DRC buffer, and return TRUE indicating that the buffer has been reloaded. 1635b775351012af176720429ac21d11682a0b75b4b7DRC It is not necessary to fill the buffer entirely, only to obtain at 1636b775351012af176720429ac21d11682a0b75b4b7DRC least one more byte. bytes_in_buffer MUST be set to a positive value 1637b775351012af176720429ac21d11682a0b75b4b7DRC if TRUE is returned. A FALSE return should only be used when I/O 1638b775351012af176720429ac21d11682a0b75b4b7DRC suspension is desired (this mode is discussed in the next section). 163936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 164036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneskip_input_data (j_decompress_ptr cinfo, long num_bytes) 1641b775351012af176720429ac21d11682a0b75b4b7DRC Skip num_bytes worth of data. The buffer pointer and count should 1642b775351012af176720429ac21d11682a0b75b4b7DRC be advanced over num_bytes input bytes, refilling the buffer as 1643b775351012af176720429ac21d11682a0b75b4b7DRC needed. This is used to skip over a potentially large amount of 1644b775351012af176720429ac21d11682a0b75b4b7DRC uninteresting data (such as an APPn marker). In some applications 1645b775351012af176720429ac21d11682a0b75b4b7DRC it may be possible to optimize away the reading of the skipped data, 1646b775351012af176720429ac21d11682a0b75b4b7DRC but it's not clear that being smart is worth much trouble; large 1647b775351012af176720429ac21d11682a0b75b4b7DRC skips are uncommon. bytes_in_buffer may be zero on return. 1648b775351012af176720429ac21d11682a0b75b4b7DRC A zero or negative skip count should be treated as a no-op. 164936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 1650bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneresync_to_restart (j_decompress_ptr cinfo, int desired) 1651b775351012af176720429ac21d11682a0b75b4b7DRC This routine is called only when the decompressor has failed to find 1652b775351012af176720429ac21d11682a0b75b4b7DRC a restart (RSTn) marker where one is expected. Its mission is to 1653b775351012af176720429ac21d11682a0b75b4b7DRC find a suitable point for resuming decompression. For most 1654b775351012af176720429ac21d11682a0b75b4b7DRC applications, we recommend that you just use the default resync 1655b775351012af176720429ac21d11682a0b75b4b7DRC procedure, jpeg_resync_to_restart(). However, if you are able to back 1656b775351012af176720429ac21d11682a0b75b4b7DRC up in the input data stream, or if you have a-priori knowledge about 1657b775351012af176720429ac21d11682a0b75b4b7DRC the likely location of restart markers, you may be able to do better. 1658b775351012af176720429ac21d11682a0b75b4b7DRC Read the read_restart_marker() and jpeg_resync_to_restart() routines 1659b775351012af176720429ac21d11682a0b75b4b7DRC in jdmarker.c if you think you'd like to implement your own resync 1660b775351012af176720429ac21d11682a0b75b4b7DRC procedure. 166136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 166236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneterm_source (j_decompress_ptr cinfo) 1663b775351012af176720429ac21d11682a0b75b4b7DRC Terminate source --- called by jpeg_finish_decompress() after all 1664b775351012af176720429ac21d11682a0b75b4b7DRC data has been read. Often a no-op. 166536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 166636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneFor both fill_input_buffer() and skip_input_data(), there is no such thing 166736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneas an EOF return. If the end of the file has been reached, the routine has 166836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanea choice of exiting via ERREXIT() or inserting fake data into the buffer. 166936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIn most cases, generating a warning message and inserting a fake EOI marker 167036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneis the best course of action --- this will allow the decompressor to output 167136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanehowever much of the image is there. In pathological cases, the decompressor 167236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemay swallow the EOI and again demand data ... just keep feeding it fake EOIs. 167336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejdatasrc.c illustrates the recommended error recovery behavior. 167436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 167536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneterm_source() is NOT called by jpeg_abort() or jpeg_destroy(). If you want 167636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe source manager to be cleaned up during an abort, you must do it yourself. 167736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 167836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou will also need code to create a jpeg_source_mgr struct, fill in its method 167936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanepointers, and insert a pointer to the struct into the "src" field of the JPEG 168036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedecompression object. This can be done in-line in your setup code if you 168136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanelike, but it's probably cleaner to provide a separate routine similar to the 1682989630f70cf1af69ebfefca8910d1647bf189712Guido Vollbedingjpeg_stdio_src() or jpeg_mem_src() routines of the supplied source managers. 168336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 1684989630f70cf1af69ebfefca8910d1647bf189712Guido VollbedingFor more information, consult the memory and stdio source and destination 1685989630f70cf1af69ebfefca8910d1647bf189712Guido Vollbedingmanagers in jdatasrc.c and jdatadst.c. 168636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 168736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 168836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneI/O suspension 168936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane-------------- 169036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 169136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneSome applications need to use the JPEG library as an incremental memory-to- 169236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanememory filter: when the compressed data buffer is filled or emptied, they want 169336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecontrol to return to the outer loop, rather than expecting that the buffer can 1694bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanebe emptied or reloaded within the data source/destination manager subroutine. 169536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe library supports this need by providing an "I/O suspension" mode, which we 169636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedescribe in this section. 169736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 1698bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe I/O suspension mode is not a panacea: nothing is guaranteed about the 1699bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanemaximum amount of time spent in any one call to the library, so it will not 1700bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneeliminate response-time problems in single-threaded applications. If you 1701bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneneed guaranteed response time, we suggest you "bite the bullet" and implement 1702bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanea real multi-tasking capability. 170336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 170436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTo use I/O suspension, cooperation is needed between the calling application 170536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneand the data source or destination manager; you will always need a custom 170636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesource/destination manager. (Please read the previous section if you haven't 170736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanealready.) The basic idea is that the empty_output_buffer() or 170836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefill_input_buffer() routine is a no-op, merely returning FALSE to indicate 170936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethat it has done nothing. Upon seeing this, the JPEG library suspends 171036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneoperation and returns to its caller. The surrounding application is 1711bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneresponsible for emptying or refilling the work buffer before calling the 1712bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneJPEG library again. 171336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 171436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneCompression suspension: 171536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 1716bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneFor compression suspension, use an empty_output_buffer() routine that returns 1717bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneFALSE; typically it will not do anything else. This will cause the 1718bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecompressor to return to the caller of jpeg_write_scanlines(), with the return 1719bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanevalue indicating that not all the supplied scanlines have been accepted. 1720bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe application must make more room in the output buffer, adjust the output 1721bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanebuffer pointer/count appropriately, and then call jpeg_write_scanlines() 172236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneagain, pointing to the first unconsumed scanline. 172336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 172436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneWhen forced to suspend, the compressor will backtrack to a convenient stopping 172536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanepoint (usually the start of the current MCU); it will regenerate some output 1726bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanedata when restarted. Therefore, although empty_output_buffer() is only 1727bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecalled when the buffer is filled, you should NOT write out the entire buffer 1728bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneafter a suspension. Write only the data up to the current position of 1729bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanenext_output_byte/free_in_buffer. The data beyond that point will be 1730bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneregenerated after resumption. 173136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 173236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneBecause of the backtracking behavior, a good-size output buffer is essential 173336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefor efficiency; you don't want the compressor to suspend often. (In fact, an 173436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneoverly small buffer could lead to infinite looping, if a single MCU required 173536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemore data than would fit in the buffer.) We recommend a buffer of at least 173636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneseveral Kbytes. You may want to insert explicit code to ensure that you don't 173736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecall jpeg_write_scanlines() unless there is a reasonable amount of space in 173836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe output buffer; in other words, flush the buffer before trying to compress 173936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemore data. 174036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 1741bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe compressor does not allow suspension while it is trying to write JPEG 1742bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanemarkers at the beginning and end of the file. This means that: 174336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * At the beginning of a compression operation, there must be enough free 174436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane space in the output buffer to hold the header markers (typically 600 or 174536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane so bytes). The recommended buffer size is bigger than this anyway, so 174636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane this is not a problem as long as you start with an empty buffer. However, 174736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane this restriction might catch you if you insert large special markers, such 1748bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane as a JFIF thumbnail image, without flushing the buffer afterwards. 174936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * When you call jpeg_finish_compress(), there must be enough space in the 175036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane output buffer to emit any buffered data and the final EOI marker. In the 175136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane current implementation, half a dozen bytes should suffice for this, but 175236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane for safety's sake we recommend ensuring that at least 100 bytes are free 175336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane before calling jpeg_finish_compress(). 1754bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1755bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneA more significant restriction is that jpeg_finish_compress() cannot suspend. 1756bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThis means you cannot use suspension with multi-pass operating modes, namely 1757bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneHuffman code optimization and multiple-scan output. Those modes write the 1758bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanewhole file during jpeg_finish_compress(), which will certainly result in 1759bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanebuffer overrun. (Note that this restriction applies only to compression, 1760bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanenot decompression. The decompressor supports input suspension in all of its 1761bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneoperating modes.) 176236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 176336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneDecompression suspension: 176436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 176536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneFor decompression suspension, use a fill_input_buffer() routine that simply 176636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanereturns FALSE (except perhaps during error recovery, as discussed below). 176736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThis will cause the decompressor to return to its caller with an indication 1768bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethat suspension has occurred. This can happen at four places: 176936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * jpeg_read_header(): will return JPEG_SUSPENDED. 1770bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane * jpeg_start_decompress(): will return FALSE, rather than its usual TRUE. 177136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * jpeg_read_scanlines(): will return the number of scanlines already 1772b775351012af176720429ac21d11682a0b75b4b7DRC completed (possibly 0). 177336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * jpeg_finish_decompress(): will return FALSE, rather than its usual TRUE. 177436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe surrounding application must recognize these cases, load more data into 177536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe input buffer, and repeat the call. In the case of jpeg_read_scanlines(), 1776bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneincrement the passed pointers past any scanlines successfully read. 177736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 177836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJust as with compression, the decompressor will typically backtrack to a 1779bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneconvenient restart point before suspending. When fill_input_buffer() is 1780bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecalled, next_input_byte/bytes_in_buffer point to the current restart point, 1781bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanewhich is where the decompressor will backtrack to if FALSE is returned. 1782bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe data beyond that position must NOT be discarded if you suspend; it needs 1783bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneto be re-read upon resumption. In most implementations, you'll need to shift 1784bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethis data down to the start of your work buffer and then load more data after 1785bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneit. Again, this behavior means that a several-Kbyte work buffer is essential 1786bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanefor decent performance; furthermore, you should load a reasonable amount of 1787bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanenew data before resuming decompression. (If you loaded, say, only one new 1788bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanebyte each time around, you could waste a LOT of cycles.) 178936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 179036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe skip_input_data() source manager routine requires special care in a 179136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesuspension scenario. This routine is NOT granted the ability to suspend the 179236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedecompressor; it can decrement bytes_in_buffer to zero, but no more. If the 179336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanerequested skip distance exceeds the amount of data currently in the input 179436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanebuffer, then skip_input_data() must set bytes_in_buffer to zero and record the 179536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneadditional skip distance somewhere else. The decompressor will immediately 1796bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecall fill_input_buffer(), which should return FALSE, which will cause a 179736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesuspension return. The surrounding application must then arrange to discard 1798bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe recorded number of bytes before it resumes loading the input buffer. 1799bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane(Yes, this design is rather baroque, but it avoids complexity in the far more 1800bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecommon case where a non-suspending source manager is used.) 180136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 180236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf the input data has been exhausted, we recommend that you emit a warning 180336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneand insert dummy EOI markers just as a non-suspending data source manager 180436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewould do. This can be handled either in the surrounding application logic or 180536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewithin fill_input_buffer(); the latter is probably more efficient. If 180636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefill_input_buffer() knows that no more data is available, it can set the 180736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanepointer/count to point to a dummy EOI marker and then return TRUE just as 180836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethough it had read more data in a non-suspending situation. 180936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 18105ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneThe decompressor does not attempt to suspend within standard JPEG markers; 18115ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneinstead it will backtrack to the start of the marker and reprocess the whole 18125ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanemarker next time. Hence the input buffer must be large enough to hold the 18135ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanelongest standard marker in the file. Standard JPEG markers should normally 18145ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanenot exceed a few hundred bytes each (DHT tables are typically the longest). 18155ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneWe recommend at least a 2K buffer for performance reasons, which is much 18165ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanelarger than any correct marker is likely to be. For robustness against 18175ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanedamaged marker length counts, you may wish to insert a test in your 18185ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneapplication for the case that the input buffer is completely full and yet 18195ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanethe decoder has suspended without consuming any data --- otherwise, if this 18205ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanesituation did occur, it would lead to an endless loop. (The library can't 18215ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneprovide this test since it has no idea whether "the buffer is full", or 18225ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneeven whether there is a fixed-size input buffer.) 18235ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 18245ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneThe input buffer would need to be 64K to allow for arbitrary COM or APPn 18255ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanemarkers, but these are handled specially: they are either saved into allocated 18265ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanememory, or skipped over by calling skip_input_data(). In the former case, 18275ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanesuspension is handled correctly, and in the latter case, the problem of 18285ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanebuffer overrun is placed on skip_input_data's shoulders, as explained above. 18295ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneNote that if you provide your own marker handling routine for large markers, 18305ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneyou should consider how to deal with buffer overflow. 183136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 18329ba2f5ed3649fb6de83d3c16e4dba1443aaca983Thomas G. LaneMultiple-buffer management: 18339ba2f5ed3649fb6de83d3c16e4dba1443aaca983Thomas G. Lane 18349ba2f5ed3649fb6de83d3c16e4dba1443aaca983Thomas G. LaneIn some applications it is desirable to store the compressed data in a linked 18359ba2f5ed3649fb6de83d3c16e4dba1443aaca983Thomas G. Lanelist of buffer areas, so as to avoid data copying. This can be handled by 18369ba2f5ed3649fb6de83d3c16e4dba1443aaca983Thomas G. Lanehaving empty_output_buffer() or fill_input_buffer() set the pointer and count 18379ba2f5ed3649fb6de83d3c16e4dba1443aaca983Thomas G. Laneto reference the next available buffer; FALSE is returned only if no more 18389ba2f5ed3649fb6de83d3c16e4dba1443aaca983Thomas G. Lanebuffers are available. Although seemingly straightforward, there is a 18399ba2f5ed3649fb6de83d3c16e4dba1443aaca983Thomas G. Lanepitfall in this approach: the backtrack that occurs when FALSE is returned 1840bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecould back up into an earlier buffer. For example, when fill_input_buffer() 1841bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneis called, the current pointer & count indicate the backtrack restart point. 1842bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneSince fill_input_buffer() will set the pointer and count to refer to a new 1843bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanebuffer, the restart position must be saved somewhere else. Suppose a second 1844bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecall to fill_input_buffer() occurs in the same library call, and no 1845bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneadditional input data is available, so fill_input_buffer must return FALSE. 1846bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneIf the JPEG library has not moved the pointer/count forward in the current 1847bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanebuffer, then *the correct restart point is the saved position in the prior 1848bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanebuffer*. Prior buffers may be discarded only after the library establishes 1849bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanea restart point within a later buffer. Similar remarks apply for output into 1850bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanea chain of buffers. 1851bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1852bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe library will never attempt to backtrack over a skip_input_data() call, 1853bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneso any skipped data can be permanently discarded. You still have to deal 1854bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanewith the case of skipping not-yet-received data, however. 1855bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1856bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneIt's much simpler to use only a single buffer; when fill_input_buffer() is 1857bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecalled, move any unconsumed data (beyond the current pointer/count) down to 1858bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe beginning of this buffer and then load new data into the remaining buffer 1859bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanespace. This approach requires a little more data copying but is far easier 1860bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneto get right. 1861bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1862bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1863bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneProgressive JPEG support 1864bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane------------------------ 1865bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1866bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneProgressive JPEG rearranges the stored data into a series of scans of 1867bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneincreasing quality. In situations where a JPEG file is transmitted across a 1868bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneslow communications link, a decoder can generate a low-quality image very 1869bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanequickly from the first scan, then gradually improve the displayed quality as 1870bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanemore scans are received. The final image after all scans are complete is 1871bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneidentical to that of a regular (sequential) JPEG file of the same quality 1872bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanesetting. Progressive JPEG files are often slightly smaller than equivalent 1873bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanesequential JPEG files, but the possibility of incremental display is the main 1874bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanereason for using progressive JPEG. 1875bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1876bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe IJG encoder library generates progressive JPEG files when given a 1877bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanesuitable "scan script" defining how to divide the data into scans. 1878bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneCreation of progressive JPEG files is otherwise transparent to the encoder. 1879bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneProgressive JPEG files can also be read transparently by the decoder library. 1880bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneIf the decoding application simply uses the library as defined above, it 1881bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanewill receive a final decoded image without any indication that the file was 1882bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneprogressive. Of course, this approach does not allow incremental display. 1883bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneTo perform incremental display, an application needs to use the decoder 1884bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanelibrary's "buffered-image" mode, in which it receives a decoded image 1885bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanemultiple times. 1886bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1887bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneEach displayed scan requires about as much work to decode as a full JPEG 1888bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneimage of the same size, so the decoder must be fairly fast in relation to the 1889bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanedata transmission rate in order to make incremental display useful. However, 1890bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneit is possible to skip displaying the image and simply add the incoming bits 1891bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneto the decoder's coefficient buffer. This is fast because only Huffman 1892bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanedecoding need be done, not IDCT, upsampling, colorspace conversion, etc. 1893bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe IJG decoder library allows the application to switch dynamically between 1894bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanedisplaying the image and simply absorbing the incoming bits. A properly 1895bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecoded application can automatically adapt the number of display passes to 1896bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanesuit the time available as the image is received. Also, a final 1897bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanehigher-quality display cycle can be performed from the buffered data after 1898bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe end of the file is reached. 1899bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1900bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneProgressive compression: 1901bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1902bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneTo create a progressive JPEG file (or a multiple-scan sequential JPEG file), 1903bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneset the scan_info cinfo field to point to an array of scan descriptors, and 1904bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneperform compression as usual. Instead of constructing your own scan list, 1905bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneyou can call the jpeg_simple_progression() helper routine to create a 1906bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanerecommended progression sequence; this method should be used by all 1907bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneapplications that don't want to get involved in the nitty-gritty of 1908bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneprogressive scan sequence design. (If you want to provide user control of 1909bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanescan sequences, you may wish to borrow the scan script reading code found 1910bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanein rdswitch.c, so that you can read scan script files just like cjpeg's.) 1911bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneWhen scan_info is not NULL, the compression library will store DCT'd data 1912bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneinto a buffer array as jpeg_write_scanlines() is called, and will emit all 1913bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe requested scans during jpeg_finish_compress(). This implies that 1914bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanemultiple-scan output cannot be created with a suspending data destination 1915bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanemanager, since jpeg_finish_compress() does not support suspension. We 1916bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneshould also note that the compressor currently forces Huffman optimization 1917bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanemode when creating a progressive JPEG file, because the default Huffman 1918bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanetables are unsuitable for progressive files. 1919bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1920bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneProgressive decompression: 1921bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1922bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneWhen buffered-image mode is not used, the decoder library will read all of 1923bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanea multi-scan file during jpeg_start_decompress(), so that it can provide a 1924bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanefinal decoded image. (Here "multi-scan" means either progressive or 1925bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanemulti-scan sequential.) This makes multi-scan files transparent to the 1926bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanedecoding application. However, existing applications that used suspending 1927bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneinput with version 5 of the IJG library will need to be modified to check 1928bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanefor a suspension return from jpeg_start_decompress(). 1929bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1930bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneTo perform incremental display, an application must use the library's 1931bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanebuffered-image mode. This is described in the next section. 1932bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1933bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1934bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneBuffered-image mode 1935bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane------------------- 1936bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1937bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneIn buffered-image mode, the library stores the partially decoded image in a 1938bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecoefficient buffer, from which it can be read out as many times as desired. 1939bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThis mode is typically used for incremental display of progressive JPEG files, 1940bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanebut it can be used with any JPEG file. Each scan of a progressive JPEG file 1941bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneadds more data (more detail) to the buffered image. The application can 1942bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanedisplay in lockstep with the source file (one display pass per input scan), 1943bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneor it can allow input processing to outrun display processing. By making 1944bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneinput and display processing run independently, it is possible for the 1945bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneapplication to adapt progressive display to a wide range of data transmission 1946bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanerates. 1947bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1948bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe basic control flow for buffered-image decoding is 1949bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1950b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_create_decompress() 1951b775351012af176720429ac21d11682a0b75b4b7DRC set data source 1952b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_read_header() 1953b775351012af176720429ac21d11682a0b75b4b7DRC set overall decompression parameters 1954b775351012af176720429ac21d11682a0b75b4b7DRC cinfo.buffered_image = TRUE; /* select buffered-image mode */ 1955b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_start_decompress() 1956b775351012af176720429ac21d11682a0b75b4b7DRC for (each output pass) { 1957b775351012af176720429ac21d11682a0b75b4b7DRC adjust output decompression parameters if required 1958b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_start_output() /* start a new output pass */ 1959b775351012af176720429ac21d11682a0b75b4b7DRC for (all scanlines in image) { 1960b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_read_scanlines() 1961b775351012af176720429ac21d11682a0b75b4b7DRC display scanlines 1962b775351012af176720429ac21d11682a0b75b4b7DRC } 1963b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_finish_output() /* terminate output pass */ 1964b775351012af176720429ac21d11682a0b75b4b7DRC } 1965b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_finish_decompress() 1966b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_destroy_decompress() 1967bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1968bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThis differs from ordinary unbuffered decoding in that there is an additional 1969bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanelevel of looping. The application can choose how many output passes to make 1970bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneand how to display each pass. 1971bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1972bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe simplest approach to displaying progressive images is to do one display 1973bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanepass for each scan appearing in the input file. In this case the outer loop 1974bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecondition is typically 1975b775351012af176720429ac21d11682a0b75b4b7DRC while (! jpeg_input_complete(&cinfo)) 1976bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneand the start-output call should read 1977b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_start_output(&cinfo, cinfo.input_scan_number); 1978bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe second parameter to jpeg_start_output() indicates which scan of the input 1979bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanefile is to be displayed; the scans are numbered starting at 1 for this 1980bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanepurpose. (You can use a loop counter starting at 1 if you like, but using 1981bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe library's input scan counter is easier.) The library automatically reads 1982bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanedata as necessary to complete each requested scan, and jpeg_finish_output() 1983bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneadvances to the next scan or end-of-image marker (hence input_scan_number 1984bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanewill be incremented by the time control arrives back at jpeg_start_output()). 1985bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneWith this technique, data is read from the input file only as needed, and 1986bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneinput and output processing run in lockstep. 1987bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1988bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneAfter reading the final scan and reaching the end of the input file, the 1989bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanebuffered image remains available; it can be read additional times by 1990bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanerepeating the jpeg_start_output()/jpeg_read_scanlines()/jpeg_finish_output() 1991bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanesequence. For example, a useful technique is to use fast one-pass color 1992bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanequantization for display passes made while the image is arriving, followed by 1993bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanea final display pass using two-pass quantization for highest quality. This 1994bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneis done by changing the library parameters before the final output pass. 1995bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneChanging parameters between passes is discussed in detail below. 1996bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 1997bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneIn general the last scan of a progressive file cannot be recognized as such 1998bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneuntil after it is read, so a post-input display pass is the best approach if 1999bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneyou want special processing in the final pass. 2000bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2001bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneWhen done with the image, be sure to call jpeg_finish_decompress() to release 2002bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe buffered image (or just use jpeg_destroy_decompress()). 2003bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2004bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneIf input data arrives faster than it can be displayed, the application can 2005bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecause the library to decode input data in advance of what's needed to produce 2006bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneoutput. This is done by calling the routine jpeg_consume_input(). 2007bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe return value is one of the following: 2008b775351012af176720429ac21d11682a0b75b4b7DRC JPEG_REACHED_SOS: reached an SOS marker (the start of a new scan) 2009b775351012af176720429ac21d11682a0b75b4b7DRC JPEG_REACHED_EOI: reached the EOI marker (end of image) 2010b775351012af176720429ac21d11682a0b75b4b7DRC JPEG_ROW_COMPLETED: completed reading one MCU row of compressed data 2011b775351012af176720429ac21d11682a0b75b4b7DRC JPEG_SCAN_COMPLETED: completed reading last MCU row of current scan 2012b775351012af176720429ac21d11682a0b75b4b7DRC JPEG_SUSPENDED: suspended before completing any of the above 2013bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane(JPEG_SUSPENDED can occur only if a suspending data source is used.) This 2014bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneroutine can be called at any time after initializing the JPEG object. It 2015bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanereads some additional data and returns when one of the indicated significant 2016bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneevents occurs. (If called after the EOI marker is reached, it will 2017bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneimmediately return JPEG_REACHED_EOI without attempting to read more data.) 2018bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2019bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe library's output processing will automatically call jpeg_consume_input() 2020bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanewhenever the output processing overtakes the input; thus, simple lockstep 2021bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanedisplay requires no direct calls to jpeg_consume_input(). But by adding 2022bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecalls to jpeg_consume_input(), you can absorb data in advance of what is 2023bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanebeing displayed. This has two benefits: 2024bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane * You can limit buildup of unprocessed data in your input buffer. 2025bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane * You can eliminate extra display passes by paying attention to the 2026bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane state of the library's input processing. 2027bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2028bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe first of these benefits only requires interspersing calls to 2029bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_consume_input() with your display operations and any other processing 2030bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneyou may be doing. To avoid wasting cycles due to backtracking, it's best to 2031bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecall jpeg_consume_input() only after a hundred or so new bytes have arrived. 2032bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThis is discussed further under "I/O suspension", above. (Note: the JPEG 2033bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanelibrary currently is not thread-safe. You must not call jpeg_consume_input() 2034bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanefrom one thread of control if a different library routine is working on the 2035bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanesame JPEG object in another thread.) 2036bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2037bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneWhen input arrives fast enough that more than one new scan is available 2038bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanebefore you start a new output pass, you may as well skip the output pass 2039bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecorresponding to the completed scan. This occurs for free if you pass 2040bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecinfo.input_scan_number as the target scan number to jpeg_start_output(). 2041bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe input_scan_number field is simply the index of the scan currently being 2042bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneconsumed by the input processor. You can ensure that this is up-to-date by 2043bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneemptying the input buffer just before calling jpeg_start_output(): call 2044bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_consume_input() repeatedly until it returns JPEG_SUSPENDED or 2045bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneJPEG_REACHED_EOI. 2046bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2047bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe target scan number passed to jpeg_start_output() is saved in the 2048bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecinfo.output_scan_number field. The library's output processing calls 2049bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_consume_input() whenever the current input scan number and row within 2050489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanethat scan is less than or equal to the current output scan number and row. 2051bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThus, input processing can "get ahead" of the output processing but is not 2052bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneallowed to "fall behind". You can achieve several different effects by 2053bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanemanipulating this interlock rule. For example, if you pass a target scan 2054bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanenumber greater than the current input scan number, the output processor will 2055bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanewait until that scan starts to arrive before producing any output. (To avoid 2056bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanean infinite loop, the target scan number is automatically reset to the last 2057bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanescan number when the end of image is reached. Thus, if you specify a large 2058bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanetarget scan number, the library will just absorb the entire input file and 2059bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethen perform an output pass. This is effectively the same as what 2060bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_start_decompress() does when you don't select buffered-image mode.) 2061bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneWhen you pass a target scan number equal to the current input scan number, 2062bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe image is displayed no faster than the current input scan arrives. The 2063bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanefinal possibility is to pass a target scan number less than the current input 2064bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanescan number; this disables the input/output interlock and causes the output 2065bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneprocessor to simply display whatever it finds in the image buffer, without 2066bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanewaiting for input. (However, the library will not accept a target scan 2067bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanenumber less than one, so you can't avoid waiting for the first scan.) 2068bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2069489583f5165e05d37302e8eeec58104ea0109127Thomas G. LaneWhen data is arriving faster than the output display processing can advance 2070489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanethrough the image, jpeg_consume_input() will store data into the buffered 2071489583f5165e05d37302e8eeec58104ea0109127Thomas G. Laneimage beyond the point at which the output processing is reading data out 2072489583f5165e05d37302e8eeec58104ea0109127Thomas G. Laneagain. If the input arrives fast enough, it may "wrap around" the buffer to 2073489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanethe point where the input is more than one whole scan ahead of the output. 2074489583f5165e05d37302e8eeec58104ea0109127Thomas G. LaneIf the output processing simply proceeds through its display pass without 2075489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanepaying attention to the input, the effect seen on-screen is that the lower 2076489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanepart of the image is one or more scans better in quality than the upper part. 2077489583f5165e05d37302e8eeec58104ea0109127Thomas G. LaneThen, when the next output scan is started, you have a choice of what target 2078489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanescan number to use. The recommended choice is to use the current input scan 2079489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanenumber at that time, which implies that you've skipped the output scans 2080489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanecorresponding to the input scans that were completed while you processed the 2081489583f5165e05d37302e8eeec58104ea0109127Thomas G. Laneprevious output scan. In this way, the decoder automatically adapts its 2082489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanespeed to the arriving data, by skipping output scans as necessary to keep up 2083489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanewith the arriving data. 2084489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lane 2085489583f5165e05d37302e8eeec58104ea0109127Thomas G. LaneWhen using this strategy, you'll want to be sure that you perform a final 2086489583f5165e05d37302e8eeec58104ea0109127Thomas G. Laneoutput pass after receiving all the data; otherwise your last display may not 2087489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanebe full quality across the whole screen. So the right outer loop logic is 2088489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanesomething like this: 2089b775351012af176720429ac21d11682a0b75b4b7DRC do { 2090b775351012af176720429ac21d11682a0b75b4b7DRC absorb any waiting input by calling jpeg_consume_input() 2091b775351012af176720429ac21d11682a0b75b4b7DRC final_pass = jpeg_input_complete(&cinfo); 2092b775351012af176720429ac21d11682a0b75b4b7DRC adjust output decompression parameters if required 2093b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_start_output(&cinfo, cinfo.input_scan_number); 2094b775351012af176720429ac21d11682a0b75b4b7DRC ... 2095b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_finish_output() 2096b775351012af176720429ac21d11682a0b75b4b7DRC } while (! final_pass); 2097bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanerather than quitting as soon as jpeg_input_complete() returns TRUE. This 2098bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanearrangement makes it simple to use higher-quality decoding parameters 2099bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanefor the final pass. But if you don't want to use special parameters for 2100bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe final pass, the right loop logic is like this: 2101b775351012af176720429ac21d11682a0b75b4b7DRC for (;;) { 2102b775351012af176720429ac21d11682a0b75b4b7DRC absorb any waiting input by calling jpeg_consume_input() 2103b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_start_output(&cinfo, cinfo.input_scan_number); 2104b775351012af176720429ac21d11682a0b75b4b7DRC ... 2105b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_finish_output() 2106b775351012af176720429ac21d11682a0b75b4b7DRC if (jpeg_input_complete(&cinfo) && 2107b775351012af176720429ac21d11682a0b75b4b7DRC cinfo.input_scan_number == cinfo.output_scan_number) 2108b775351012af176720429ac21d11682a0b75b4b7DRC break; 2109b775351012af176720429ac21d11682a0b75b4b7DRC } 2110489583f5165e05d37302e8eeec58104ea0109127Thomas G. LaneIn this case you don't need to know in advance whether an output pass is to 2111489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanebe the last one, so it's not necessary to have reached EOF before starting 2112489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanethe final output pass; rather, what you want to test is whether the output 2113489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanepass was performed in sync with the final input scan. This form of the loop 2114489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanewill avoid an extra output pass whenever the decoder is able (or nearly able) 2115489583f5165e05d37302e8eeec58104ea0109127Thomas G. Laneto keep up with the incoming data. 2116bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2117bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneWhen the data transmission speed is high, you might begin a display pass, 2118489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanethen find that much or all of the file has arrived before you can complete 2119bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe pass. (You can detect this by noting the JPEG_REACHED_EOI return code 2120bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanefrom jpeg_consume_input(), or equivalently by testing jpeg_input_complete().) 2121bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneIn this situation you may wish to abort the current display pass and start a 2122bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanenew one using the newly arrived information. To do so, just call 2123bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_finish_output() and then start a new pass with jpeg_start_output(). 2124bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2125bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneA variant strategy is to abort and restart display if more than one complete 2126bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanescan arrives during an output pass; this can be detected by noting 2127bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneJPEG_REACHED_SOS returns and/or examining cinfo.input_scan_number. This 2128bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneidea should be employed with caution, however, since the display process 2129bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanemight never get to the bottom of the image before being aborted, resulting 2130bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanein the lower part of the screen being several passes worse than the upper. 2131bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneIn most cases it's probably best to abort an output pass only if the whole 2132bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanefile has arrived and you want to begin the final output pass immediately. 2133bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2134bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneWhen receiving data across a communication link, we recommend always using 2135bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe current input scan number for the output target scan number; if a 2136bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanehigher-quality final pass is to be done, it should be started (aborting any 2137bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneincomplete output pass) as soon as the end of file is received. However, 2138bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanemany other strategies are possible. For example, the application can examine 2139bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe parameters of the current input scan and decide whether to display it or 2140bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanenot. If the scan contains only chroma data, one might choose not to use it 2141bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneas the target scan, expecting that the scan will be small and will arrive 2142bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanequickly. To skip to the next scan, call jpeg_consume_input() until it 2143bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanereturns JPEG_REACHED_SOS or JPEG_REACHED_EOI. Or just use the next higher 2144bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanenumber as the target scan for jpeg_start_output(); but that method doesn't 2145bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanelet you inspect the next scan's parameters before deciding to display it. 2146bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2147bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2148bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneIn buffered-image mode, jpeg_start_decompress() never performs input and 2149bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethus never suspends. An application that uses input suspension with 2150bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanebuffered-image mode must be prepared for suspension returns from these 2151bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneroutines: 2152bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane* jpeg_start_output() performs input only if you request 2-pass quantization 2153bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane and the target scan isn't fully read yet. (This is discussed below.) 2154bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane* jpeg_read_scanlines(), as always, returns the number of scanlines that it 2155bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane was able to produce before suspending. 2156bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane* jpeg_finish_output() will read any markers following the target scan, 2157489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lane up to the end of the file or the SOS marker that begins another scan. 2158bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane (But it reads no input if jpeg_consume_input() has already reached the 2159489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lane end of the file or a SOS marker beyond the target output scan.) 2160489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lane* jpeg_finish_decompress() will read until the end of file, and thus can 2161bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane suspend if the end hasn't already been reached (as can be tested by 2162bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane calling jpeg_input_complete()). 2163bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_start_output(), jpeg_finish_output(), and jpeg_finish_decompress() 2164bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneall return TRUE if they completed their tasks, FALSE if they had to suspend. 2165bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneIn the event of a FALSE return, the application must load more input data 2166bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneand repeat the call. Applications that use non-suspending data sources need 2167bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanenot check the return values of these three routines. 2168bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2169bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2170bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneIt is possible to change decoding parameters between output passes in the 2171bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanebuffered-image mode. The decoder library currently supports only very 2172bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanelimited changes of parameters. ONLY THE FOLLOWING parameter changes are 2173bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneallowed after jpeg_start_decompress() is called: 2174bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane* dct_method can be changed before each call to jpeg_start_output(). 2175bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane For example, one could use a fast DCT method for early scans, changing 2176bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane to a higher quality method for the final scan. 2177bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane* dither_mode can be changed before each call to jpeg_start_output(); 2178bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane of course this has no impact if not using color quantization. Typically 2179bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane one would use ordered dither for initial passes, then switch to 2180bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane Floyd-Steinberg dither for the final pass. Caution: changing dither mode 2181bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane can cause more memory to be allocated by the library. Although the amount 2182bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane of memory involved is not large (a scanline or so), it may cause the 2183bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane initial max_memory_to_use specification to be exceeded, which in the worst 2184bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane case would result in an out-of-memory failure. 2185bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane* do_block_smoothing can be changed before each call to jpeg_start_output(). 2186bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane This setting is relevant only when decoding a progressive JPEG image. 2187bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane During the first DC-only scan, block smoothing provides a very "fuzzy" look 2188bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane instead of the very "blocky" look seen without it; which is better seems a 2189bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane matter of personal taste. But block smoothing is nearly always a win 2190bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane during later stages, especially when decoding a successive-approximation 2191bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane image: smoothing helps to hide the slight blockiness that otherwise shows 2192bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane up on smooth gradients until the lowest coefficient bits are sent. 2193bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane* Color quantization mode can be changed under the rules described below. 2194bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane You *cannot* change between full-color and quantized output (because that 2195bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane would alter the required I/O buffer sizes), but you can change which 2196bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane quantization method is used. 2197bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2198bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneWhen generating color-quantized output, changing quantization method is a 2199bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanevery useful way of switching between high-speed and high-quality display. 2200bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe library allows you to change among its three quantization methods: 2201bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane1. Single-pass quantization to a fixed color cube. 2202bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane Selected by cinfo.two_pass_quantize = FALSE and cinfo.colormap = NULL. 2203bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane2. Single-pass quantization to an application-supplied colormap. 2204bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane Selected by setting cinfo.colormap to point to the colormap (the value of 2205bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane two_pass_quantize is ignored); also set cinfo.actual_number_of_colors. 2206bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane3. Two-pass quantization to a colormap chosen specifically for the image. 2207bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane Selected by cinfo.two_pass_quantize = TRUE and cinfo.colormap = NULL. 2208bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane (This is the default setting selected by jpeg_read_header, but it is 2209bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane probably NOT what you want for the first pass of progressive display!) 2210bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThese methods offer successively better quality and lesser speed. However, 2211bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneonly the first method is available for quantizing in non-RGB color spaces. 2212bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2213bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneIMPORTANT: because the different quantizer methods have very different 2214bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneworking-storage requirements, the library requires you to indicate which 2215bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneone(s) you intend to use before you call jpeg_start_decompress(). (If we did 2216bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanenot require this, the max_memory_to_use setting would be a complete fiction.) 2217bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneYou do this by setting one or more of these three cinfo fields to TRUE: 2218b775351012af176720429ac21d11682a0b75b4b7DRC enable_1pass_quant Fixed color cube colormap 2219b775351012af176720429ac21d11682a0b75b4b7DRC enable_external_quant Externally-supplied colormap 2220b775351012af176720429ac21d11682a0b75b4b7DRC enable_2pass_quant Two-pass custom colormap 2221bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneAll three are initialized FALSE by jpeg_read_header(). But 2222bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_start_decompress() automatically sets TRUE the one selected by the 2223bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecurrent two_pass_quantize and colormap settings, so you only need to set the 2224bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneenable flags for any other quantization methods you plan to change to later. 2225bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2226bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneAfter setting the enable flags correctly at jpeg_start_decompress() time, you 2227bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecan change to any enabled quantization method by setting two_pass_quantize 2228bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneand colormap properly just before calling jpeg_start_output(). The following 2229bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanespecial rules apply: 2230bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane1. You must explicitly set cinfo.colormap to NULL when switching to 1-pass 2231bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane or 2-pass mode from a different mode, or when you want the 2-pass 2232bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane quantizer to be re-run to generate a new colormap. 2233bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane2. To switch to an external colormap, or to change to a different external 2234bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane colormap than was used on the prior pass, you must call 2235bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane jpeg_new_colormap() after setting cinfo.colormap. 2236bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneNOTE: if you want to use the same colormap as was used in the prior pass, 2237bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneyou should not do either of these things. This will save some nontrivial 2238bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneswitchover costs. 2239bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane(These requirements exist because cinfo.colormap will always be non-NULL 2240bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneafter completing a prior output pass, since both the 1-pass and 2-pass 2241bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanequantizers set it to point to their output colormaps. Thus you have to 2242bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanedo one of these two things to notify the library that something has changed. 2243bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneYup, it's a bit klugy, but it's necessary to do it this way for backwards 2244bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecompatibility.) 2245bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2246bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneNote that in buffered-image mode, the library generates any requested colormap 2247bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneduring jpeg_start_output(), not during jpeg_start_decompress(). 2248bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2249bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneWhen using two-pass quantization, jpeg_start_output() makes a pass over the 2250bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanebuffered image to determine the optimum color map; it therefore may take a 2251bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanesignificant amount of time, whereas ordinarily it does little work. The 2252bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneprogress monitor hook is called during this pass, if defined. It is also 2253bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneimportant to realize that if the specified target scan number is greater than 2254bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneor equal to the current input scan number, jpeg_start_output() will attempt 2255bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneto consume input as it makes this pass. If you use a suspending data source, 2256bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneyou need to check for a FALSE return from jpeg_start_output() under these 2257bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneconditions. The combination of 2-pass quantization and a not-yet-fully-read 2258bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanetarget scan is the only case in which jpeg_start_output() will consume input. 2259bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2260bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2261bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneApplication authors who support buffered-image mode may be tempted to use it 2262bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanefor all JPEG images, even single-scan ones. This will work, but it is 2263bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneinefficient: there is no need to create an image-sized coefficient buffer for 2264bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanesingle-scan images. Requesting buffered-image mode for such an image wastes 2265bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanememory. Worse, it can cost time on large images, since the buffered data has 2266bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneto be swapped out or written to a temporary file. If you are concerned about 2267bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanemaximum performance on baseline JPEG files, you should use buffered-image 2268bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanemode only when the incoming file actually has multiple scans. This can be 2269bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanetested by calling jpeg_has_multiple_scans(), which will return a correct 2270bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneresult at any time after jpeg_read_header() completes. 2271bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2272bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneIt is also worth noting that when you use jpeg_consume_input() to let input 2273bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneprocessing get ahead of output processing, the resulting pattern of access to 2274bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe coefficient buffer is quite nonsequential. It's best to use the memory 2275bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanemanager jmemnobs.c if you can (ie, if you have enough real or virtual main 2276bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanememory). If not, at least make sure that max_memory_to_use is set as high as 2277bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanepossible. If the JPEG memory manager has to use a temporary file, you will 2278bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneprobably see a lot of disk traffic and poor performance. (This could be 2279bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneimproved with additional work on the memory manager, but we haven't gotten 2280bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanearound to it yet.) 2281bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2282bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneIn some applications it may be convenient to use jpeg_consume_input() for all 2283bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneinput processing, including reading the initial markers; that is, you may 2284bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanewish to call jpeg_consume_input() instead of jpeg_read_header() during 2285bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanestartup. This works, but note that you must check for JPEG_REACHED_SOS and 2286bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneJPEG_REACHED_EOI return codes as the equivalent of jpeg_read_header's codes. 2287bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneOnce the first SOS marker has been reached, you must call 2288bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_start_decompress() before jpeg_consume_input() will consume more input; 2289bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneit'll just keep returning JPEG_REACHED_SOS until you do. If you read a 2290bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanetables-only file this way, jpeg_consume_input() will return JPEG_REACHED_EOI 2291bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanewithout ever returning JPEG_REACHED_SOS; be sure to check for this case. 2292bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneIf this happens, the decompressor will not read any more input until you call 2293bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_abort() to reset it. It is OK to call jpeg_consume_input() even when not 2294bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneusing buffered-image mode, but in that case it's basically a no-op after the 2295bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneinitial markers have been read: it will just return JPEG_SUSPENDED. 22969ba2f5ed3649fb6de83d3c16e4dba1443aaca983Thomas G. Lane 229736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 229836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAbbreviated datastreams and multiple images 229936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane------------------------------------------- 230036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 230136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneA JPEG compression or decompression object can be reused to process multiple 230236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneimages. This saves a small amount of time per image by eliminating the 230336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane"create" and "destroy" operations, but that isn't the real purpose of the 230436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefeature. Rather, reuse of an object provides support for abbreviated JPEG 230536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedatastreams. Object reuse can also simplify processing a series of images in 230636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanea single input or output file. This section explains these features. 230736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 230836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneA JPEG file normally contains several hundred bytes worth of quantization 230936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneand Huffman tables. In a situation where many images will be stored or 231036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanetransmitted with identical tables, this may represent an annoying overhead. 231136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe JPEG standard therefore permits tables to be omitted. The standard 231236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedefines three classes of JPEG datastreams: 231336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * "Interchange" datastreams contain an image and all tables needed to decode 231436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane the image. These are the usual kind of JPEG file. 231536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * "Abbreviated image" datastreams contain an image, but are missing some or 231636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane all of the tables needed to decode that image. 231736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * "Abbreviated table specification" (henceforth "tables-only") datastreams 231836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane contain only table specifications. 231936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTo decode an abbreviated image, it is necessary to load the missing table(s) 232036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneinto the decoder beforehand. This can be accomplished by reading a separate 232136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanetables-only file. A variant scheme uses a series of images in which the first 232236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneimage is an interchange (complete) datastream, while subsequent ones are 232336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneabbreviated and rely on the tables loaded by the first image. It is assumed 232436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethat once the decoder has read a table, it will remember that table until a 232536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanenew definition for the same table number is encountered. 232636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 232736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIt is the application designer's responsibility to figure out how to associate 232836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe correct tables with an abbreviated image. While abbreviated datastreams 232936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecan be useful in a closed environment, their use is strongly discouraged in 233036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneany situation where data exchange with other applications might be needed. 233136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneCaveat designer. 233236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 233336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe JPEG library provides support for reading and writing any combination of 233436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanetables-only datastreams and abbreviated images. In both compression and 233536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedecompression objects, a quantization or Huffman table will be retained for 233636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe lifetime of the object, unless it is overwritten by a new table definition. 233736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 233836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 233936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTo create abbreviated image datastreams, it is only necessary to tell the 234036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecompressor not to emit some or all of the tables it is using. Each 234136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanequantization and Huffman table struct contains a boolean field "sent_table", 234236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewhich normally is initialized to FALSE. For each table used by the image, the 234336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneheader-writing process emits the table and sets sent_table = TRUE unless it is 234436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanealready TRUE. (In normal usage, this prevents outputting the same table 234536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedefinition multiple times, as would otherwise occur because the chroma 234636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecomponents typically share tables.) Thus, setting this field to TRUE before 234736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecalling jpeg_start_compress() will prevent the table from being written at 234836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneall. 234936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 235036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf you want to create a "pure" abbreviated image file containing no tables, 235136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejust call "jpeg_suppress_tables(&cinfo, TRUE)" after constructing all the 235236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanetables. If you want to emit some but not all tables, you'll need to set the 235336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneindividual sent_table fields directly. 235436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 235536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTo create an abbreviated image, you must also call jpeg_start_compress() 235636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewith a second parameter of FALSE, not TRUE. Otherwise jpeg_start_compress() 235736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewill force all the sent_table fields to FALSE. (This is a safety feature to 235836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneprevent abbreviated images from being created accidentally.) 235936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 236036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTo create a tables-only file, perform the same parameter setup that you 236136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanenormally would, but instead of calling jpeg_start_compress() and so on, call 236236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_write_tables(&cinfo). This will write an abbreviated datastream 236336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecontaining only SOI, DQT and/or DHT markers, and EOI. All the quantization 236436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneand Huffman tables that are currently defined in the compression object will 236536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanebe emitted unless their sent_tables flag is already TRUE, and then all the 236636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesent_tables flags will be set TRUE. 236736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 236836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneA sure-fire way to create matching tables-only and abbreviated image files 236936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneis to proceed as follows: 237036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 2371b775351012af176720429ac21d11682a0b75b4b7DRC create JPEG compression object 2372b775351012af176720429ac21d11682a0b75b4b7DRC set JPEG parameters 2373b775351012af176720429ac21d11682a0b75b4b7DRC set destination to tables-only file 2374b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_write_tables(&cinfo); 2375b775351012af176720429ac21d11682a0b75b4b7DRC set destination to image file 2376b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_start_compress(&cinfo, FALSE); 2377b775351012af176720429ac21d11682a0b75b4b7DRC write data... 2378b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_finish_compress(&cinfo); 237936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 238036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneSince the JPEG parameters are not altered between writing the table file and 238136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe abbreviated image file, the same tables are sure to be used. Of course, 238236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneyou can repeat the jpeg_start_compress() ... jpeg_finish_compress() sequence 238336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemany times to produce many abbreviated image files matching the table file. 238436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 238536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou cannot suppress output of the computed Huffman tables when Huffman 238636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneoptimization is selected. (If you could, there'd be no way to decode the 238736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneimage...) Generally, you don't want to set optimize_coding = TRUE when 238836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneyou are trying to produce abbreviated files. 238936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 239036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIn some cases you might want to compress an image using tables which are 239136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanenot stored in the application, but are defined in an interchange or 239236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanetables-only file readable by the application. This can be done by setting up 239336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanea JPEG decompression object to read the specification file, then copying the 2394489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanetables into your compression object. See jpeg_copy_critical_parameters() 2395489583f5165e05d37302e8eeec58104ea0109127Thomas G. Lanefor an example of copying quantization tables. 239636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 239736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 239836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTo read abbreviated image files, you simply need to load the proper tables 239936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneinto the decompression object before trying to read the abbreviated image. 240036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf the proper tables are stored in the application program, you can just 24015ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneallocate the table structs and fill in their contents directly. For example, 24025ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneto load a fixed quantization table into table slot "n": 24035ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 24045ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane if (cinfo.quant_tbl_ptrs[n] == NULL) 24055ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane cinfo.quant_tbl_ptrs[n] = jpeg_alloc_quant_table((j_common_ptr) &cinfo); 2406b775351012af176720429ac21d11682a0b75b4b7DRC quant_ptr = cinfo.quant_tbl_ptrs[n]; /* quant_ptr is JQUANT_TBL* */ 24075ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane for (i = 0; i < 64; i++) { 24085ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane /* Qtable[] is desired quantization table, in natural array order */ 24095ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane quant_ptr->quantval[i] = Qtable[i]; 24105ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane } 24115ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 24125ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneCode to load a fixed Huffman table is typically (for AC table "n"): 24135ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 24145ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane if (cinfo.ac_huff_tbl_ptrs[n] == NULL) 24155ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane cinfo.ac_huff_tbl_ptrs[n] = jpeg_alloc_huff_table((j_common_ptr) &cinfo); 2416b775351012af176720429ac21d11682a0b75b4b7DRC huff_ptr = cinfo.ac_huff_tbl_ptrs[n]; /* huff_ptr is JHUFF_TBL* */ 24175ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane for (i = 1; i <= 16; i++) { 24185ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane /* counts[i] is number of Huffman codes of length i bits, i=1..16 */ 24195ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane huff_ptr->bits[i] = counts[i]; 24205ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane } 24215ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane for (i = 0; i < 256; i++) { 24225ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane /* symbols[] is the list of Huffman symbols, in code-length order */ 24235ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane huff_ptr->huffval[i] = symbols[i]; 24245ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane } 24255ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 24265ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane(Note that trying to set cinfo.quant_tbl_ptrs[n] to point directly at a 24275ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneconstant JQUANT_TBL object is not safe. If the incoming file happened to 24285ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanecontain a quantization table definition, your master table would get 24295ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneoverwritten! Instead allocate a working table copy and copy the master table 24305ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneinto it, as illustrated above. Ditto for Huffman tables, of course.) 24315ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 24325ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneYou might want to read the tables from a tables-only file, rather than 24335ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanehard-wiring them into your application. The jpeg_read_header() call is 24345ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanesufficient to read a tables-only file. You must pass a second parameter of 24355ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneFALSE to indicate that you do not require an image to be present. Thus, the 24365ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanetypical scenario is 243736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 2438b775351012af176720429ac21d11682a0b75b4b7DRC create JPEG decompression object 2439b775351012af176720429ac21d11682a0b75b4b7DRC set source to tables-only file 2440b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_read_header(&cinfo, FALSE); 2441b775351012af176720429ac21d11682a0b75b4b7DRC set source to abbreviated image file 2442b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_read_header(&cinfo, TRUE); 2443b775351012af176720429ac21d11682a0b75b4b7DRC set decompression parameters 2444b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_start_decompress(&cinfo); 2445b775351012af176720429ac21d11682a0b75b4b7DRC read data... 2446b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_finish_decompress(&cinfo); 244736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 244836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIn some cases, you may want to read a file without knowing whether it contains 244936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanean image or just tables. In that case, pass FALSE and check the return value 245036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefrom jpeg_read_header(): it will be JPEG_HEADER_OK if an image was found, 245136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJPEG_HEADER_TABLES_ONLY if only tables were found. (A third return value, 245236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJPEG_SUSPENDED, is possible when using a suspending data source manager.) 245336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneNote that jpeg_read_header() will not complain if you read an abbreviated 245436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneimage for which you haven't loaded the missing tables; the missing-table check 2455bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneoccurs later, in jpeg_start_decompress(). 245636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 245736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 245836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIt is possible to read a series of images from a single source file by 245936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanerepeating the jpeg_read_header() ... jpeg_finish_decompress() sequence, 246036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewithout releasing/recreating the JPEG object or the data source module. 246136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane(If you did reinitialize, any partial bufferload left in the data source 246236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanebuffer at the end of one image would be discarded, causing you to lose the 246336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanestart of the next image.) When you use this method, stored tables are 246436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneautomatically carried forward, so some of the images can be abbreviated images 246536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethat depend on tables from earlier images. 246636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 246736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf you intend to write a series of images into a single destination file, 246836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneyou might want to make a specialized data destination module that doesn't 246936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneflush the output buffer at term_destination() time. This would speed things 247036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneup by some trifling amount. Of course, you'd need to remember to flush the 247136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanebuffer after the last image. You can make the later images be abbreviated 247236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneones by passing FALSE to jpeg_start_compress(). 247336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 247436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 247536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneSpecial markers 247636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane--------------- 247736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 247836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneSome applications may need to insert or extract special data in the JPEG 247936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedatastream. The JPEG standard provides marker types "COM" (comment) and 248036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane"APP0" through "APP15" (application) to hold application-specific data. 248136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneUnfortunately, the use of these markers is not specified by the standard. 248236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneCOM markers are fairly widely used to hold user-supplied text. The JFIF file 248336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneformat spec uses APP0 markers with specified initial strings to hold certain 248436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedata. Adobe applications use APP14 markers beginning with the string "Adobe" 248536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefor miscellaneous data. Other APPn markers are rarely seen, but might 248636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecontain almost anything. 248736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 248836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf you wish to store user-supplied text, we recommend you use COM markers 248936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneand place readable 7-bit ASCII text in them. Newline conventions are not 249036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanestandardized --- expect to find LF (Unix style), CR/LF (DOS style), or CR 249136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane(Mac style). A robust COM reader should be able to cope with random binary 249236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanegarbage, including nulls, since some applications generate COM markers 249336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecontaining non-ASCII junk. (But yours should not be one of them.) 249436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 249536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneFor program-supplied data, use an APPn marker, and be sure to begin it with an 249636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneidentifying string so that you can tell whether the marker is actually yours. 249736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIt's probably best to avoid using APP0 or APP14 for any private markers. 2498bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane(NOTE: the upcoming SPIFF standard will use APP8 markers; we recommend you 2499bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanenot use APP8 markers for any private purposes, either.) 250036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 250136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneKeep in mind that at most 65533 bytes can be put into one marker, but you 250236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecan have as many markers as you like. 250336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 2504bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneBy default, the IJG compression library will write a JFIF APP0 marker if the 250536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneselected JPEG colorspace is grayscale or YCbCr, or an Adobe APP14 marker if 250636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe selected colorspace is RGB, CMYK, or YCCK. You can disable this, but 250736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewe don't recommend it. The decompression library will recognize JFIF and 250836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAdobe markers and will set the JPEG colorspace properly when one is found. 250936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 25105ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 251136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou can write special markers immediately following the datastream header by 251236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecalling jpeg_write_marker() after jpeg_start_compress() and before the first 251336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecall to jpeg_write_scanlines(). When you do this, the markers appear after 251436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe SOI and the JFIF APP0 and Adobe APP14 markers (if written), but before 2515bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneall else. Specify the marker type parameter as "JPEG_COM" for COM or 251636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane"JPEG_APP0 + n" for APPn. (Actually, jpeg_write_marker will let you write 251736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneany marker type, but we don't recommend writing any other kinds of marker.) 251836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneFor example, to write a user comment string pointed to by comment_text: 2519b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_write_marker(cinfo, JPEG_COM, comment_text, strlen(comment_text)); 25205ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 25215ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneIf it's not convenient to store all the marker data in memory at once, 25225ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneyou can instead call jpeg_write_m_header() followed by multiple calls to 25235ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanejpeg_write_m_byte(). If you do it this way, it's your responsibility to 25245ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanecall jpeg_write_m_byte() exactly the number of times given in the length 25255ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneparameter to jpeg_write_m_header(). (This method lets you empty the 25265ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneoutput buffer partway through a marker, which might be important when 25275ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneusing a suspending data destination module. In any case, if you are using 25285ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanea suspending destination, you should flush its buffer after inserting 25295ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneany special markers. See "I/O suspension".) 25305ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 25315ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneOr, if you prefer to synthesize the marker byte sequence yourself, 25325ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneyou can just cram it straight into the data destination module. 25335ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 25345ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneIf you are writing JFIF 1.02 extension markers (thumbnail images), don't 25355ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneforget to set cinfo.JFIF_minor_version = 2 so that the encoder will write the 25365ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanecorrect JFIF version number in the JFIF header marker. The library's default 25375ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneis to write version 1.01, but that's wrong if you insert any 1.02 extension 25385ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanemarkers. (We could probably get away with just defaulting to 1.02, but there 25395ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneused to be broken decoders that would complain about unknown minor version 25405ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanenumbers. To reduce compatibility risks it's safest not to write 1.02 unless 25415ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneyou are actually using 1.02 extensions.) 25425ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 25435ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 25445ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneWhen reading, two methods of handling special markers are available: 25455ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane1. You can ask the library to save the contents of COM and/or APPn markers 25465ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneinto memory, and then examine them at your leisure afterwards. 25475ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane2. You can supply your own routine to process COM and/or APPn markers 25485ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneon-the-fly as they are read. 25495ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneThe first method is simpler to use, especially if you are using a suspending 25505ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanedata source; writing a marker processor that copes with input suspension is 25515ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanenot easy (consider what happens if the marker is longer than your available 25525ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneinput buffer). However, the second method conserves memory since the marker 25535ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanedata need not be kept around after it's been processed. 25545ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 25555ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneFor either method, you'd normally set up marker handling after creating a 25565ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanedecompression object and before calling jpeg_read_header(), because the 25575ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanemarkers of interest will typically be near the head of the file and so will 25585ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanebe scanned by jpeg_read_header. Once you've established a marker handling 25595ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanemethod, it will be used for the life of that decompression object 25605ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane(potentially many datastreams), unless you change it. Marker handling is 25615ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanedetermined separately for COM markers and for each APPn marker code. 25625ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 25635ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 25645ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneTo save the contents of special markers in memory, call 2565b775351012af176720429ac21d11682a0b75b4b7DRC jpeg_save_markers(cinfo, marker_code, length_limit) 25665ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanewhere marker_code is the marker type to save, JPEG_COM or JPEG_APP0+n. 25675ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane(To arrange to save all the special marker types, you need to call this 25685ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneroutine 17 times, for COM and APP0-APP15.) If the incoming marker is longer 25695ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanethan length_limit data bytes, only length_limit bytes will be saved; this 25705ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneparameter allows you to avoid chewing up memory when you only need to see the 25715ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanefirst few bytes of a potentially large marker. If you want to save all the 25725ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanedata, set length_limit to 0xFFFF; that is enough since marker lengths are only 25735ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane16 bits. As a special case, setting length_limit to 0 prevents that marker 25745ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanetype from being saved at all. (That is the default behavior, in fact.) 25755ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 25765ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneAfter jpeg_read_header() completes, you can examine the special markers by 25775ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanefollowing the cinfo->marker_list pointer chain. All the special markers in 25785ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanethe file appear in this list, in order of their occurrence in the file (but 25795ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneomitting any markers of types you didn't ask for). Both the original data 25805ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanelength and the saved data length are recorded for each list entry; the latter 25815ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanewill not exceed length_limit for the particular marker type. Note that these 25825ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanelengths exclude the marker length word, whereas the stored representation 25835ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanewithin the JPEG file includes it. (Hence the maximum data length is really 25845ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneonly 65533.) 25855ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 25865ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneIt is possible that additional special markers appear in the file beyond the 25875ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneSOS marker at which jpeg_read_header stops; if so, the marker list will be 25885ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneextended during reading of the rest of the file. This is not expected to be 25895ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanecommon, however. If you are short on memory you may want to reset the length 25905ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanelimit to zero for all marker types after finishing jpeg_read_header, to 25915ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneensure that the max_memory_to_use setting cannot be exceeded due to addition 25925ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneof later markers. 25935ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 25945ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneThe marker list remains stored until you call jpeg_finish_decompress or 25955ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanejpeg_abort, at which point the memory is freed and the list is set to empty. 25965ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane(jpeg_destroy also releases the storage, of course.) 25975ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 25985ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneNote that the library is internally interested in APP0 and APP14 markers; 25995ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneif you try to set a small nonzero length limit on these types, the library 26005ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanewill silently force the length up to the minimum it wants. (But you can set 26015ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanea zero length limit to prevent them from being saved at all.) Also, in a 26025ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane16-bit environment, the maximum length limit may be constrained to less than 26035ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane65533 by malloc() limitations. It is therefore best not to assume that the 26045ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneeffective length limit is exactly what you set it to be. 26055ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 26065ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 26075ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneIf you want to supply your own marker-reading routine, you do it by calling 26085ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanejpeg_set_marker_processor(). A marker processor routine must have the 26095ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanesignature 2610b775351012af176720429ac21d11682a0b75b4b7DRC boolean jpeg_marker_parser_method (j_decompress_ptr cinfo) 261136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAlthough the marker code is not explicitly passed, the routine can find it 261236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanein cinfo->unread_marker. At the time of call, the marker proper has been 261336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneread from the data source module. The processor routine is responsible for 261436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanereading the marker length word and the remaining parameter bytes, if any. 261536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneReturn TRUE to indicate success. (FALSE should be returned only if you are 261636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneusing a suspending data source and it tells you to suspend. See the standard 261736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemarker processors in jdmarker.c for appropriate coding methods if you need to 261836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneuse a suspending data source.) 261936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 262036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf you override the default APP0 or APP14 processors, it is up to you to 262136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanerecognize JFIF and Adobe markers if you want colorspace recognition to occur 262236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneproperly. We recommend copying and extending the default processors if you 26235ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanewant to do that. (A better idea is to save these marker types for later 26245ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneexamination by calling jpeg_save_markers(); that method doesn't interfere 26255ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanewith the library's own processing of these markers.) 26265ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 26275ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanejpeg_set_marker_processor() and jpeg_save_markers() are mutually exclusive 26285ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane--- if you call one it overrides any previous call to the other, for the 26295ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneparticular marker type specified. 263036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 263136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneA simple example of an external COM processor can be found in djpeg.c. 26325ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneAlso, see jpegtran.c for an example of using jpeg_save_markers. 263336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 263436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 263536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneRaw (downsampled) image data 263636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane---------------------------- 263736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 263836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneSome applications need to supply already-downsampled image data to the JPEG 263936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecompressor, or to receive raw downsampled data from the decompressor. The 264036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanelibrary supports this requirement by allowing the application to write or 264136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneread raw data, bypassing the normal preprocessing or postprocessing steps. 264236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe interface is different from the standard one and is somewhat harder to 264336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneuse. If your interest is merely in bypassing color conversion, we recommend 264436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethat you use the standard interface and simply set jpeg_color_space = 264536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanein_color_space (or jpeg_color_space = out_color_space for decompression). 264636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe mechanism described in this section is necessary only to supply or 264736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanereceive downsampled image data, in which not all components have the same 264836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedimensions. 264936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 265036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 265136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTo compress raw data, you must supply the data in the colorspace to be used 265236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanein the JPEG file (please read the earlier section on Special color spaces) 265336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneand downsampled to the sampling factors specified in the JPEG parameters. 265436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou must supply the data in the format used internally by the JPEG library, 265536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanenamely a JSAMPIMAGE array. This is an array of pointers to two-dimensional 265636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanearrays, each of type JSAMPARRAY. Each 2-D array holds the values for one 265736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecolor component. This structure is necessary since the components are of 265836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedifferent sizes. If the image dimensions are not a multiple of the MCU size, 265936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneyou must also pad the data correctly (usually, this is done by replicating 266036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe last column and/or row). The data must be padded to a multiple of a DCT 266136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneblock in each component: that is, each downsampled row must contain a 266236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemultiple of 8 valid samples, and there must be a multiple of 8 sample rows 266336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefor each component. (For applications such as conversion of digital TV 266436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneimages, the standard image size is usually a multiple of the DCT block size, 266536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneso that no padding need actually be done.) 266636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 266736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe procedure for compression of raw data is basically the same as normal 266836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecompression, except that you call jpeg_write_raw_data() in place of 266936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_write_scanlines(). Before calling jpeg_start_compress(), you must do 267036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe following: 267136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * Set cinfo->raw_data_in to TRUE. (It is set FALSE by jpeg_set_defaults().) 267236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane This notifies the library that you will be supplying raw data. 267336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * Ensure jpeg_color_space is correct --- an explicit jpeg_set_colorspace() 267436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane call is a good idea. Note that since color conversion is bypassed, 267536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane in_color_space is ignored, except that jpeg_set_defaults() uses it to 267636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane choose the default jpeg_color_space setting. 267736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane * Ensure the sampling factors, cinfo->comp_info[i].h_samp_factor and 267836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane cinfo->comp_info[i].v_samp_factor, are correct. Since these indicate the 267936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane dimensions of the data you are supplying, it's wise to set them 268036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane explicitly, rather than assuming the library's defaults are what you want. 268136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 268236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTo pass raw data to the library, call jpeg_write_raw_data() in place of 268336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_write_scanlines(). The two routines work similarly except that 268436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_write_raw_data takes a JSAMPIMAGE data array rather than JSAMPARRAY. 268536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe scanlines count passed to and returned from jpeg_write_raw_data is 268636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemeasured in terms of the component with the largest v_samp_factor. 268736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 268836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_write_raw_data() processes one MCU row per call, which is to say 268936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanev_samp_factor*DCTSIZE sample rows of each component. The passed num_lines 269036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanevalue must be at least max_v_samp_factor*DCTSIZE, and the return value will 269136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanebe exactly that amount (or possibly some multiple of that amount, in future 269236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanelibrary versions). This is true even on the last call at the bottom of the 269336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneimage; don't forget to pad your data as necessary. 269436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 269536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe required dimensions of the supplied data can be computed for each 269636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecomponent as 2697b775351012af176720429ac21d11682a0b75b4b7DRC cinfo->comp_info[i].width_in_blocks*DCTSIZE samples per row 2698b775351012af176720429ac21d11682a0b75b4b7DRC cinfo->comp_info[i].height_in_blocks*DCTSIZE rows in image 269936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneafter jpeg_start_compress() has initialized those fields. If the valid data 270036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneis smaller than this, it must be padded appropriately. For some sampling 270136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefactors and image sizes, additional dummy DCT blocks are inserted to make 270236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe image a multiple of the MCU dimensions. The library creates such dummy 270336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneblocks itself; it does not read them from your supplied data. Therefore you 270436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneneed never pad by more than DCTSIZE samples. An example may help here. 270536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAssume 2h2v downsampling of YCbCr data, that is 2706b775351012af176720429ac21d11682a0b75b4b7DRC cinfo->comp_info[0].h_samp_factor = 2 for Y 2707b775351012af176720429ac21d11682a0b75b4b7DRC cinfo->comp_info[0].v_samp_factor = 2 2708b775351012af176720429ac21d11682a0b75b4b7DRC cinfo->comp_info[1].h_samp_factor = 1 for Cb 2709b775351012af176720429ac21d11682a0b75b4b7DRC cinfo->comp_info[1].v_samp_factor = 1 2710b775351012af176720429ac21d11682a0b75b4b7DRC cinfo->comp_info[2].h_samp_factor = 1 for Cr 2711b775351012af176720429ac21d11682a0b75b4b7DRC cinfo->comp_info[2].v_samp_factor = 1 271236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneand suppose that the nominal image dimensions (cinfo->image_width and 271336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecinfo->image_height) are 101x101 pixels. Then jpeg_start_compress() will 271436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecompute downsampled_width = 101 and width_in_blocks = 13 for Y, 271536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedownsampled_width = 51 and width_in_blocks = 7 for Cb and Cr (and the same 271636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefor the height fields). You must pad the Y data to at least 13*8 = 104 271736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecolumns and rows, the Cb/Cr data to at least 7*8 = 56 columns and rows. The 271836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneMCU height is max_v_samp_factor = 2 DCT rows so you must pass at least 16 271936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanescanlines on each call to jpeg_write_raw_data(), which is to say 16 actual 272036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanesample rows of Y and 8 each of Cb and Cr. A total of 7 MCU rows are needed, 272136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneso you must pass a total of 7*16 = 112 "scanlines". The last DCT block row 272236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneof Y data is dummy, so it doesn't matter what you pass for it in the data 272336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanearrays, but the scanlines count must total up to 112 so that all of the Cb 272436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneand Cr data gets passed. 272536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 2726a8b67c4fbbfde9b4b4e03f2dea8f4f0b1900fc33Thomas G. LaneOutput suspension is supported with raw-data compression: if the data 2727a8b67c4fbbfde9b4b4e03f2dea8f4f0b1900fc33Thomas G. Lanedestination module suspends, jpeg_write_raw_data() will return 0. 2728a8b67c4fbbfde9b4b4e03f2dea8f4f0b1900fc33Thomas G. LaneIn this case the same data rows must be passed again on the next call. 272936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 273036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 273136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneDecompression with raw data output implies bypassing all postprocessing: 2732bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneyou cannot ask for rescaling or color quantization, for instance. More 2733bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneseriously, you must deal with the color space and sampling factors present in 2734bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe incoming file. If your application only handles, say, 2h1v YCbCr data, 2735bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneyou must check for and fail on other color spaces or other sampling factors. 2736bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe library will not convert to a different color space for you. 273736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 273836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTo obtain raw data output, set cinfo->raw_data_out = TRUE before 273936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_start_decompress() (it is set FALSE by jpeg_read_header()). Be sure to 274036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneverify that the color space and sampling factors are ones you can handle. 274136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThen call jpeg_read_raw_data() in place of jpeg_read_scanlines(). The 274236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedecompression process is otherwise the same as usual. 274336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 274436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_read_raw_data() returns one MCU row per call, and thus you must pass a 274536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanebuffer of at least max_v_samp_factor*DCTSIZE scanlines (scanline counting is 274636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe same as for raw-data compression). The buffer you pass must be large 274736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneenough to hold the actual data plus padding to DCT-block boundaries. As with 274836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecompression, any entirely dummy DCT blocks are not processed so you need not 274936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneallocate space for them, but the total scanline count includes them. The 275036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneabove example of computing buffer dimensions for raw-data compression is 275136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneequally valid for decompression. 275236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 275336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneInput suspension is supported with raw-data decompression: if the data source 2754bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanemodule suspends, jpeg_read_raw_data() will return 0. You can also use 2755bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanebuffered-image mode to read raw data in multiple passes. 2756bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2757bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2758bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneReally raw data: DCT coefficients 2759bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane--------------------------------- 2760bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2761bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneIt is possible to read or write the contents of a JPEG file as raw DCT 2762bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecoefficients. This facility is mainly intended for use in lossless 2763bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanetranscoding between different JPEG file formats. Other possible applications 2764bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneinclude lossless cropping of a JPEG image, lossless reassembly of a 2765bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanemulti-strip or multi-tile TIFF/JPEG file into a single JPEG datastream, etc. 2766bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2767bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneTo read the contents of a JPEG file as DCT coefficients, open the file and do 2768bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_read_header() as usual. But instead of calling jpeg_start_decompress() 2769bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneand jpeg_read_scanlines(), call jpeg_read_coefficients(). This will read the 2770bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneentire image into a set of virtual coefficient-block arrays, one array per 2771bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecomponent. The return value is a pointer to an array of virtual-array 2772bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanedescriptors. Each virtual array can be accessed directly using the JPEG 2773bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanememory manager's access_virt_barray method (see Memory management, below, 27745996a25e2f50d20d6a8f09830724035b49c3927bGuido Vollbedingand also read structure.txt's discussion of virtual array handling). Or, 2775bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanefor simple transcoding to a different JPEG file format, the array list can 2776bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejust be handed directly to jpeg_write_coefficients(). 2777bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 27785ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneEach block in the block arrays contains quantized coefficient values in 27795ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanenormal array order (not JPEG zigzag order). The block arrays contain only 27805ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneDCT blocks containing real data; any entirely-dummy blocks added to fill out 27815ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneinterleaved MCUs at the right or bottom edges of the image are discarded 27825ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneduring reading and are not stored in the block arrays. (The size of each 27835ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneblock array can be determined from the width_in_blocks and height_in_blocks 27845ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanefields of the component's comp_info entry.) This is also the data format 27855ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneexpected by jpeg_write_coefficients(). 27865ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 2787bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneWhen you are done using the virtual arrays, call jpeg_finish_decompress() 2788bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneto release the array storage and return the decompression object to an idle 2789bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanestate; or just call jpeg_destroy() if you don't need to reuse the object. 2790bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2791bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneIf you use a suspending data source, jpeg_read_coefficients() will return 2792bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneNULL if it is forced to suspend; a non-NULL return value indicates successful 2793bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanecompletion. You need not test for a NULL return value when using a 2794bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanenon-suspending data source. 2795bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 27965ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneIt is also possible to call jpeg_read_coefficients() to obtain access to the 27975ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanedecoder's coefficient arrays during a normal decode cycle in buffered-image 27985ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanemode. This frammish might be useful for progressively displaying an incoming 27995ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneimage and then re-encoding it without loss. To do this, decode in buffered- 28005ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneimage mode as discussed previously, then call jpeg_read_coefficients() after 28015ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanethe last jpeg_finish_output() call. The arrays will be available for your use 28025ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneuntil you call jpeg_finish_decompress(). 28035ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 2804bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2805bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneTo write the contents of a JPEG file as DCT coefficients, you must provide 2806bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe DCT coefficients stored in virtual block arrays. You can either pass 2807bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneblock arrays read from an input JPEG file by jpeg_read_coefficients(), or 2808bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneallocate virtual arrays from the JPEG compression object and fill them 2809bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneyourself. In either case, jpeg_write_coefficients() is substituted for 2810bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_start_compress() and jpeg_write_scanlines(). Thus the sequence is 2811bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane * Create compression object 2812bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane * Set all compression parameters as necessary 2813bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane * Request virtual arrays if needed 2814bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane * jpeg_write_coefficients() 2815bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane * jpeg_finish_compress() 2816bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane * Destroy or re-use compression object 2817bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_write_coefficients() is passed a pointer to an array of virtual block 2818bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanearray descriptors; the number of arrays is equal to cinfo.num_components. 2819bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2820bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe virtual arrays need only have been requested, not realized, before 2821bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_write_coefficients() is called. A side-effect of 2822bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_write_coefficients() is to realize any virtual arrays that have been 2823bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanerequested from the compression object's memory manager. Thus, when obtaining 2824bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe virtual arrays from the compression object, you should fill the arrays 2825bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneafter calling jpeg_write_coefficients(). The data is actually written out 2826bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanewhen you call jpeg_finish_compress(); jpeg_write_coefficients() only writes 2827bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe file header. 2828bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2829bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneWhen writing raw DCT coefficients, it is crucial that the JPEG quantization 2830bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanetables and sampling factors match the way the data was encoded, or the 2831bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneresulting file will be invalid. For transcoding from an existing JPEG file, 2832bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanewe recommend using jpeg_copy_critical_parameters(). This routine initializes 2833bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneall the compression parameters to default values (like jpeg_set_defaults()), 2834bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethen copies the critical information from a source decompression object. 2835bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneThe decompression object should have just been used to read the entire 2836bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneJPEG input file --- that is, it should be awaiting jpeg_finish_decompress(). 2837bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2838bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_write_coefficients() marks all tables stored in the compression object 2839bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneas needing to be written to the output file (thus, it acts like 2840bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_start_compress(cinfo, TRUE)). This is for safety's sake, to avoid 2841bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneemitting abbreviated JPEG files by accident. If you really want to emit an 2842bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneabbreviated JPEG file, call jpeg_suppress_tables(), or set the tables' 2843bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneindividual sent_table flags, between calling jpeg_write_coefficients() and 2844bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanejpeg_finish_compress(). 284536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 284636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 284736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneProgress monitoring 284836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane------------------- 284936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 285036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneSome applications may need to regain control from the JPEG library every so 285136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneoften. The typical use of this feature is to produce a percent-done bar or 285236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneother progress display. (For a simple example, see cjpeg.c or djpeg.c.) 285336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAlthough you do get control back frequently during the data-transferring pass 285436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane(the jpeg_read_scanlines or jpeg_write_scanlines loop), any additional passes 285536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewill occur inside jpeg_finish_compress or jpeg_start_decompress; those 285636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneroutines may take a long time to execute, and you don't get control back 285736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneuntil they are done. 285836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 285936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou can define a progress-monitor routine which will be called periodically 286036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneby the library. No guarantees are made about how often this call will occur, 286136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneso we don't recommend you use it for mouse tracking or anything like that. 286236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAt present, a call will occur once per MCU row, scanline, or sample row 286336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanegroup, whichever unit is convenient for the current processing mode; so the 2864bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanewider the image, the longer the time between calls. During the data 286536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanetransferring pass, only one call occurs per call of jpeg_read_scanlines or 286636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_write_scanlines, so don't pass a large number of scanlines at once if 2867bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneyou want fine resolution in the progress count. (If you really need to use 2868bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanethe callback mechanism for time-critical tasks like mouse tracking, you could 2869bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneinsert additional calls inside some of the library's inner loops.) 287036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 287136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneTo establish a progress-monitor callback, create a struct jpeg_progress_mgr, 287236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefill in its progress_monitor field with a pointer to your callback routine, 287336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneand set cinfo->progress to point to the struct. The callback will be called 287436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewhenever cinfo->progress is non-NULL. (This pointer is set to NULL by 287536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_create_compress or jpeg_create_decompress; the library will not change 287636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneit thereafter. So if you allocate dynamic storage for the progress struct, 287736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemake sure it will live as long as the JPEG object does. Allocating from the 287836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneJPEG memory manager with lifetime JPOOL_PERMANENT will work nicely.) You 287936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecan use the same callback routine for both compression and decompression. 288036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 288136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe jpeg_progress_mgr struct contains four fields which are set by the library: 2882b775351012af176720429ac21d11682a0b75b4b7DRC long pass_counter; /* work units completed in this pass */ 2883b775351012af176720429ac21d11682a0b75b4b7DRC long pass_limit; /* total number of work units in this pass */ 2884b775351012af176720429ac21d11682a0b75b4b7DRC int completed_passes; /* passes completed so far */ 2885b775351012af176720429ac21d11682a0b75b4b7DRC int total_passes; /* total number of passes expected */ 288636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneDuring any one pass, pass_counter increases from 0 up to (not including) 2887bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanepass_limit; the step size is usually but not necessarily 1. The pass_limit 2888bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanevalue may change from one pass to another. The expected total number of 288936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanepasses is in total_passes, and the number of passes already completed is in 289036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecompleted_passes. Thus the fraction of work completed may be estimated as 2891b775351012af176720429ac21d11682a0b75b4b7DRC completed_passes + (pass_counter/pass_limit) 2892b775351012af176720429ac21d11682a0b75b4b7DRC -------------------------------------------- 2893b775351012af176720429ac21d11682a0b75b4b7DRC total_passes 289436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneignoring the fact that the passes may not be equal amounts of work. 289536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 2896bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneWhen decompressing, pass_limit can even change within a pass, because it 289736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedepends on the number of scans in the JPEG file, which isn't always known in 2898bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneadvance. The computed fraction-of-work-done may jump suddenly (if the library 2899bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanediscovers it has overestimated the number of scans) or even decrease (in the 2900bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneopposite case). It is not wise to put great faith in the work estimate. 2901bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lane 2902bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneWhen using the decompressor's buffered-image mode, the progress monitor work 2903bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneestimate is likely to be completely unhelpful, because the library has no way 2904bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneto know how many output passes will be demanded of it. Currently, the library 2905bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanesets total_passes based on the assumption that there will be one more output 2906bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanepass if the input file end hasn't yet been read (jpeg_input_complete() isn't 2907bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. LaneTRUE), but no more output passes if the file end has been reached when the 2908bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneoutput pass is started. This means that total_passes will rise as additional 2909bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneoutput passes are requested. If you have a way of determining the input file 2910bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanesize, estimating progress based on the fraction of the file that's been read 2911bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Lanewill probably be more useful than using the library's value. 291236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 291336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 291436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneMemory management 291536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane----------------- 291636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 291736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThis section covers some key facts about the JPEG library's built-in memory 29185996a25e2f50d20d6a8f09830724035b49c3927bGuido Vollbedingmanager. For more info, please read structure.txt's section about the memory 291936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemanager, and consult the source code if necessary. 292036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 292136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneAll memory and temporary file allocation within the library is done via the 292236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanememory manager. If necessary, you can replace the "back end" of the memory 292336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemanager to control allocation yourself (for example, if you don't want the 292436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanelibrary to use malloc() and free() for some reason). 292536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 292636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneSome data is allocated "permanently" and will not be freed until the JPEG 292736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneobject is destroyed. Most data is allocated "per image" and is freed by 292836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejpeg_finish_compress, jpeg_finish_decompress, or jpeg_abort. You can call the 292936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanememory manager yourself to allocate structures that will automatically be 293036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefreed at these times. Typical code for this is 293136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane ptr = (*cinfo->mem->alloc_small) ((j_common_ptr) cinfo, JPOOL_IMAGE, size); 293236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneUse JPOOL_PERMANENT to get storage that lasts as long as the JPEG object. 293336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneUse alloc_large instead of alloc_small for anything bigger than a few Kbytes. 293436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThere are also alloc_sarray and alloc_barray routines that automatically 293536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanebuild 2-D sample or block arrays. 293636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 293736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe library's minimum space requirements to process an image depend on the 293836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneimage's width, but not on its height, because the library ordinarily works 293936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanewith "strip" buffers that are as wide as the image but just a few rows high. 294036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneSome operating modes (eg, two-pass color quantization) require full-image 294136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanebuffers. Such buffers are treated as "virtual arrays": only the current strip 294236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneneed be in memory, and the rest can be swapped out to a temporary file. 294336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 294436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIf you use the simplest memory manager back end (jmemnobs.c), then no 294536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanetemporary files are used; virtual arrays are simply malloc()'d. Images bigger 294636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethan memory can be processed only if your system supports virtual memory. 294736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe other memory manager back ends support temporary files of various flavors 294836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneand thus work in machines without virtual memory. They may also be useful on 294936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneUnix machines if you need to process images that exceed available swap space. 295036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 295136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneWhen using temporary files, the library will make the in-memory buffers for 295236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneits virtual arrays just big enough to stay within a "maximum memory" setting. 295336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYour application can set this limit by setting cinfo->mem->max_memory_to_use 295436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneafter creating the JPEG object. (Of course, there is still a minimum size for 295536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe buffers, so the max-memory setting is effective only if it is bigger than 295636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe minimum space needed.) If you allocate any large structures yourself, you 295736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemust allocate them before jpeg_start_compress() or jpeg_start_decompress() in 295836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneorder to have them counted against the max memory limit. Also keep in mind 295936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethat space allocated with alloc_small() is ignored, on the assumption that 2960bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneit's too small to be worth worrying about; so a reasonable safety margin 2961bc79e0680a45d1ca330d690dae0340c8e17ab5e3Thomas G. Laneshould be left when setting max_memory_to_use. 296236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 296336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 29645ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneMemory usage 29655ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane------------ 29665ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 29675ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneWorking memory requirements while performing compression or decompression 29685ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanedepend on image dimensions, image characteristics (such as colorspace and 29695ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneJPEG process), and operating mode (application-selected options). 29705ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 29715ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneAs of v6b, the decompressor requires: 29725ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 1. About 24K in more-or-less-fixed-size data. This varies a bit depending 29735ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane on operating mode and image characteristics (particularly color vs. 29745ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane grayscale), but it doesn't depend on image dimensions. 29755ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 2. Strip buffers (of size proportional to the image width) for IDCT and 29765ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane upsampling results. The worst case for commonly used sampling factors 29775ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane is about 34 bytes * width in pixels for a color image. A grayscale image 29785ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane only needs about 8 bytes per pixel column. 29795ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 3. A full-image DCT coefficient buffer is needed to decode a multi-scan JPEG 29805ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane file (including progressive JPEGs), or whenever you select buffered-image 29815ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane mode. This takes 2 bytes/coefficient. At typical 2x2 sampling, that's 29825ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 3 bytes per pixel for a color image. Worst case (1x1 sampling) requires 29835ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 6 bytes/pixel. For grayscale, figure 2 bytes/pixel. 29845ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 4. To perform 2-pass color quantization, the decompressor also needs a 29855ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 128K color lookup table and a full-image pixel buffer (3 bytes/pixel). 29865ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneThis does not count any memory allocated by the application, such as a 29875ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanebuffer to hold the final output image. 29885ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 29895ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneThe above figures are valid for 8-bit JPEG data precision and a machine with 29905ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane32-bit ints. For 12-bit JPEG data, double the size of the strip buffers and 29915ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanequantization pixel buffer. The "fixed-size" data will be somewhat smaller 29925ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanewith 16-bit ints, larger with 64-bit ints. Also, CMYK or other unusual 29935ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanecolor spaces will require different amounts of space. 29945ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 29955ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneThe full-image coefficient and pixel buffers, if needed at all, do not 29965ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanehave to be fully RAM resident; you can have the library use temporary 29975ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanefiles instead when the total memory usage would exceed a limit you set. 29985ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane(But if your OS supports virtual memory, it's probably better to just use 29995ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanejmemnobs and let the OS do the swapping.) 30005ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 30015ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneThe compressor's memory requirements are similar, except that it has no need 30025ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanefor color quantization. Also, it needs a full-image DCT coefficient buffer 30035ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneif Huffman-table optimization is asked for, even if progressive mode is not 30045ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanerequested. 30055ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 30065ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneIf you need more detailed information about memory usage in a particular 30075ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanesituation, you can enable the MEM_STATS code in jmemmgr.c. 30085ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 30095ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 301036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneLibrary compile-time options 301136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane---------------------------- 301236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 301336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneA number of compile-time options are available by modifying jmorecfg.h. 301436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 301536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe JPEG standard provides for both the baseline 8-bit DCT process and 30165ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanea 12-bit DCT process. The IJG code supports 12-bit lossy JPEG if you define 301736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneBITS_IN_JSAMPLE as 12 rather than 8. Note that this causes JSAMPLE to be 301836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanelarger than a char, so it affects the surrounding application's image data. 30199ba2f5ed3649fb6de83d3c16e4dba1443aaca983Thomas G. LaneThe sample applications cjpeg and djpeg can support 12-bit mode only for PPM 30209ba2f5ed3649fb6de83d3c16e4dba1443aaca983Thomas G. Laneand GIF file formats; you must disable the other file formats to compile a 30215996a25e2f50d20d6a8f09830724035b49c3927bGuido Vollbeding12-bit cjpeg or djpeg. (install.txt has more information about that.) 3022a8b67c4fbbfde9b4b4e03f2dea8f4f0b1900fc33Thomas G. LaneAt present, a 12-bit library can handle *only* 12-bit images, not both 302352ded8768022ab7e9e7670ddea0ba89e2890b837DRCprecisions. 3024a8b67c4fbbfde9b4b4e03f2dea8f4f0b1900fc33Thomas G. Lane 3025a8b67c4fbbfde9b4b4e03f2dea8f4f0b1900fc33Thomas G. LaneNote that a 12-bit library always compresses in Huffman optimization mode, 3026a8b67c4fbbfde9b4b4e03f2dea8f4f0b1900fc33Thomas G. Lanein order to generate valid Huffman tables. This is necessary because our 3027a8b67c4fbbfde9b4b4e03f2dea8f4f0b1900fc33Thomas G. Lanedefault Huffman tables only cover 8-bit data. If you need to output 12-bit 3028a8b67c4fbbfde9b4b4e03f2dea8f4f0b1900fc33Thomas G. Lanefiles in one pass, you'll have to supply suitable default Huffman tables. 30295ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneYou may also want to supply your own DCT quantization tables; the existing 30305ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanequality-scaling code has been developed for 8-bit use, and probably doesn't 30315ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanegenerate especially good tables for 12-bit. 303236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 303336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe maximum number of components (color channels) in the image is determined 303436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneby MAX_COMPONENTS. The JPEG standard allows up to 255 components, but we 303536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneexpect that few applications will need more than four or so. 303636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 303736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneOn machines with unusual data type sizes, you may be able to improve 303836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneperformance or reduce memory space by tweaking the various typedefs in 303936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejmorecfg.h. In particular, on some RISC CPUs, access to arrays of "short"s 304036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneis quite slow; consider trading memory for speed by making JCOEF, INT16, and 304136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneUINT16 be "int" or "unsigned int". UINT8 is also a candidate to become int. 304236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou probably don't want to make JSAMPLE be int unless you have lots of memory 304336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneto burn. 304436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 304536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneYou can reduce the size of the library by compiling out various optional 304636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanefunctions. To do this, undefine xxx_SUPPORTED symbols as necessary. 304736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 30485ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. LaneYou can also save a few K by not having text error messages in the library; 30495ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanethe standard error message table occupies about 5Kb. This is particularly 3050b775351012af176720429ac21d11682a0b75b4b7DRCreasonable for embedded applications where there's no good way to display 30515ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanea message anyway. To do this, remove the creation of the message table 30525ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane(jpeg_std_message_table[]) from jerror.c, and alter format_message to do 30535ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanesomething reasonable without it. You could output the numeric value of the 30545ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanemessage code number, for example. If you do this, you can also save a couple 30555ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lanemore K by modifying the TRACEMSn() macros in jerror.h to expand to nothing; 30565ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Laneyou don't need trace capability anyway, right? 30575ead57a34a398aa798f35bd7a6abad19b2e453e2Thomas G. Lane 305836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 305936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LanePortability considerations 306036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane-------------------------- 306136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 306236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe JPEG library has been written to be extremely portable; the sample 306336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneapplications cjpeg and djpeg are slightly less so. This section summarizes 306436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethe design goals in this area. (If you encounter any bugs that cause the 306536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanelibrary to be less portable than is claimed here, we'd appreciate hearing 306636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneabout them.) 306736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 3068fced14c7b47fd329345ff39da96b9262cd94a299DRCThe code works fine on ANSI C and C++ compilers, using any of the popular 3069fced14c7b47fd329345ff39da96b9262cd94a299DRCsystem include file setups, and some not-so-popular ones too. 307036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 307136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe code is not dependent on the exact sizes of the C data types. As 307236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedistributed, we make the assumptions that 3073b775351012af176720429ac21d11682a0b75b4b7DRC char is at least 8 bits wide 3074b775351012af176720429ac21d11682a0b75b4b7DRC short is at least 16 bits wide 3075b775351012af176720429ac21d11682a0b75b4b7DRC int is at least 16 bits wide 3076b775351012af176720429ac21d11682a0b75b4b7DRC long is at least 32 bits wide 307736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane(These are the minimum requirements of the ANSI C standard.) Wider types will 307836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanework fine, although memory may be used inefficiently if char is much larger 307936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethan 8 bits or short is much bigger than 16 bits. The code should work 308036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneequally well with 16- or 32-bit ints. 308136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 308236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneIn a system where these assumptions are not met, you may be able to make the 308336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanecode work by modifying the typedefs in jmorecfg.h. However, you will probably 308436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanehave difficulty if int is less than 16 bits wide, since references to plain 308536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneint abound in the code. 308636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 308736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanechar can be either signed or unsigned, although the code runs faster if an 308836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneunsigned char type is available. If char is wider than 8 bits, you will need 308936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneto redefine JOCTET and/or provide custom data source/destination managers so 309036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanethat JOCTET represents exactly 8 bits of data on external storage. 309136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 309236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe JPEG library proper does not assume ASCII representation of characters. 309336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneBut some of the image file I/O modules in cjpeg/djpeg do have ASCII 309436a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanedependencies in file-header manipulation; so does cjpeg's select_file_type() 309536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneroutine. 309636a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 309736a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. LaneThe JPEG library does not rely heavily on the C library. In particular, C 309836a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanestdio is used only by the data source/destination modules and the error 309936a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanehandler, all of which are application-replaceable. (cjpeg/djpeg are more 310036a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Laneheavily dependent on stdio.) malloc and free are called only from the memory 310136a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanemanager "back end" module, so you can use a different memory allocator by 310236a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanereplacing that one file. 310336a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lane 31045996a25e2f50d20d6a8f09830724035b49c3927bGuido VollbedingMore info about porting the code may be gleaned by reading jconfig.txt, 310536a4ccccd33f5cc9df62949554af87129ced7f84Thomas G. Lanejmorecfg.h, and jinclude.h. 3106