1 USING THE IJG JPEG LIBRARY

     2 

     3 Copyright (C) 1994-2009, Thomas G. Lane, Guido Vollbeding.

     4 This file is part of the Independent JPEG Group's software.

     5 For conditions of distribution and use, see the accompanying README file.

     6 

     7 

     8 This file describes how to use the IJG JPEG library within an application

     9 program.  Read it if you want to write a program that uses the library.

    10 

    11 The file example.c provides heavily commented skeleton code for calling the

    12 JPEG library.  Also see jpeglib.h (the include file to be used by application

    13 programs) for full details about data structures and function parameter lists.

    14 The library source code, of course, is the ultimate reference.

    15 

    16 Note that there have been *major* changes from the application interface

    17 presented by IJG version 4 and earlier versions.  The old design had several

    18 inherent limitations, and it had accumulated a lot of cruft as we added

    19 features while trying to minimize application-interface changes.  We have

    20 sacrificed backward compatibility in the version 5 rewrite, but we think the

    21 improvements justify this.

    22 

    23 

    24 TABLE OF CONTENTS

    25 -----------------

    26 

    27 Overview:

    28 	Functions provided by the library

    29 	Outline of typical usage

    30 Basic library usage:

    31 	Data formats

    32 	Compression details

    33 	Decompression details

    34 	Mechanics of usage: include files, linking, etc

    35 Advanced features:

    36 	Compression parameter selection

    37 	Decompression parameter selection

    38 	Special color spaces

    39 	Error handling

    40 	Compressed data handling (source and destination managers)

    41 	I/O suspension

    42 	Progressive JPEG support

    43 	Buffered-image mode

    44 	Abbreviated datastreams and multiple images

    45 	Special markers

    46 	Raw (downsampled) image data

    47 	Really raw data: DCT coefficients

    48 	Progress monitoring

    49 	Memory management

    50 	Memory usage

    51 	Library compile-time options

    52 	Portability considerations

    53 	Notes for MS-DOS implementors

    54 

    55 You should read at least the overview and basic usage sections before trying

    56 to program with the library.  The sections on advanced features can be read

    57 if and when you need them.

    58 

    59 

    60 OVERVIEW

    61 ========

    62 

    63 Functions provided by the library

    64 ---------------------------------

    65 

    66 The IJG JPEG library provides C code to read and write JPEG-compressed image

    67 files.  The surrounding application program receives or supplies image data a

    68 scanline at a time, using a straightforward uncompressed image format.  All

    69 details of color conversion and other preprocessing/postprocessing can be

    70 handled by the library.

    71 

    72 The library includes a substantial amount of code that is not covered by the

    73 JPEG standard but is necessary for typical applications of JPEG.  These

    74 functions preprocess the image before JPEG compression or postprocess it after

    75 decompression.  They include colorspace conversion, downsampling/upsampling,

    76 and color quantization.  The application indirectly selects use of this code

    77 by specifying the format in which it wishes to supply or receive image data.

    78 For example, if colormapped output is requested, then the decompression

    79 library automatically invokes color quantization.

    80 

    81 A wide range of quality vs. speed tradeoffs are possible in JPEG processing,

    82 and even more so in decompression postprocessing.  The decompression library

    83 provides multiple implementations that cover most of the useful tradeoffs,

    84 ranging from very-high-quality down to fast-preview operation.  On the

    85 compression side we have generally not provided low-quality choices, since

    86 compression is normally less time-critical.  It should be understood that the

    87 low-quality modes may not meet the JPEG standard's accuracy requirements;

    88 nonetheless, they are useful for viewers.

    89 

    90 A word about functions *not* provided by the library.  We handle a subset of

    91 the ISO JPEG standard; most baseline, extended-sequential, and progressive

    92 JPEG processes are supported.  (Our subset includes all features now in common

    93 use.)  Unsupported ISO options include:

    94 	* Hierarchical storage

    95 	* Lossless JPEG

    96 	* DNL marker

    97 	* Nonintegral subsampling ratios

    98 We support both 8- and 12-bit data precision, but this is a compile-time

    99 choice rather than a run-time choice; hence it is difficult to use both

   100 precisions in a single application.

   101 

   102 By itself, the library handles only interchange JPEG datastreams --- in

   103 particular the widely used JFIF file format.  The library can be used by

   104 surrounding code to process interchange or abbreviated JPEG datastreams that

   105 are embedded in more complex file formats.  (For example, this library is

   106 used by the free LIBTIFF library to support JPEG compression in TIFF.)

   107 

   108 

   109 Outline of typical usage

   110 ------------------------

   111 

   112 The rough outline of a JPEG compression operation is:

   113 

   114 	Allocate and initialize a JPEG compression object

   115 	Specify the destination for the compressed data (eg, a file)

   116 	Set parameters for compression, including image size & colorspace

   117 	jpeg_start_compress(...);

   118 	while (scan lines remain to be written)

   119 		jpeg_write_scanlines(...);

   120 	jpeg_finish_compress(...);

   121 	Release the JPEG compression object

   122 

   123 A JPEG compression object holds parameters and working state for the JPEG

   124 library.  We make creation/destruction of the object separate from starting

   125 or finishing compression of an image; the same object can be re-used for a

   126 series of image compression operations.  This makes it easy to re-use the

   127 same parameter settings for a sequence of images.  Re-use of a JPEG object

   128 also has important implications for processing abbreviated JPEG datastreams,

   129 as discussed later.

   130 

   131 The image data to be compressed is supplied to jpeg_write_scanlines() from

   132 in-memory buffers.  If the application is doing file-to-file compression,

   133 reading image data from the source file is the application's responsibility.

   134 The library emits compressed data by calling a "data destination manager",

   135 which typically will write the data into a file; but the application can

   136 provide its own destination manager to do something else.

   137 

   138 Similarly, the rough outline of a JPEG decompression operation is:

   139 

   140 	Allocate and initialize a JPEG decompression object

   141 	Specify the source of the compressed data (eg, a file)

   142 	Call jpeg_read_header() to obtain image info

   143 	Set parameters for decompression

   144 	jpeg_start_decompress(...);

   145 	while (scan lines remain to be read)

   146 		jpeg_read_scanlines(...);

   147 	jpeg_finish_decompress(...);

   148 	Release the JPEG decompression object

   149 

   150 This is comparable to the compression outline except that reading the

   151 datastream header is a separate step.  This is helpful because information

   152 about the image's size, colorspace, etc is available when the application

   153 selects decompression parameters.  For example, the application can choose an

   154 output scaling ratio that will fit the image into the available screen size.

   155 

   156 The decompression library obtains compressed data by calling a data source

   157 manager, which typically will read the data from a file; but other behaviors

   158 can be obtained with a custom source manager.  Decompressed data is delivered

   159 into in-memory buffers passed to jpeg_read_scanlines().

   160 

   161 It is possible to abort an incomplete compression or decompression operation

   162 by calling jpeg_abort(); or, if you do not need to retain the JPEG object,

   163 simply release it by calling jpeg_destroy().

   164 

   165 JPEG compression and decompression objects are two separate struct types.

   166 However, they share some common fields, and certain routines such as

   167 jpeg_destroy() can work on either type of object.

   168 

   169 The JPEG library has no static variables: all state is in the compression

   170 or decompression object.  Therefore it is possible to process multiple

   171 compression and decompression operations concurrently, using multiple JPEG

   172 objects.

   173 

   174 Both compression and decompression can be done in an incremental memory-to-

   175 memory fashion, if suitable source/destination managers are used.  See the

   176 section on "I/O suspension" for more details.

   177 

   178 

   179 BASIC LIBRARY USAGE

   180 ===================

   181 

   182 Data formats

   183 ------------

   184 

   185 Before diving into procedural details, it is helpful to understand the

   186 image data format that the JPEG library expects or returns.

   187 

   188 The standard input image format is a rectangular array of pixels, with each

   189 pixel having the same number of "component" or "sample" values (color

   190 channels).  You must specify how many components there are and the colorspace

   191 interpretation of the components.  Most applications will use RGB data

   192 (three components per pixel) or grayscale data (one component per pixel).

   193 PLEASE NOTE THAT RGB DATA IS THREE SAMPLES PER PIXEL, GRAYSCALE ONLY ONE.

   194 A remarkable number of people manage to miss this, only to find that their

   195 programs don't work with grayscale JPEG files.

   196 

   197 There is no provision for colormapped input.  JPEG files are always full-color

   198 or full grayscale (or sometimes another colorspace such as CMYK).  You can

   199 feed in a colormapped image by expanding it to full-color format.  However

   200 JPEG often doesn't work very well with source data that has been colormapped,

   201 because of dithering noise.  This is discussed in more detail in the JPEG FAQ

   202 and the other references mentioned in the README file.

   203 

   204 Pixels are stored by scanlines, with each scanline running from left to

   205 right.  The component values for each pixel are adjacent in the row; for

   206 example, R,G,B,R,G,B,R,G,B,... for 24-bit RGB color.  Each scanline is an

   207 array of data type JSAMPLE --- which is typically "unsigned char", unless

   208 you've changed jmorecfg.h.  (You can also change the RGB pixel layout, say

   209 to B,G,R order, by modifying jmorecfg.h.  But see the restrictions listed in

   210 that file before doing so.)

   211 

   212 A 2-D array of pixels is formed by making a list of pointers to the starts of

   213 scanlines; so the scanlines need not be physically adjacent in memory.  Even

   214 if you process just one scanline at a time, you must make a one-element

   215 pointer array to conform to this structure.  Pointers to JSAMPLE rows are of

   216 type JSAMPROW, and the pointer to the pointer array is of type JSAMPARRAY.

   217 

   218 The library accepts or supplies one or more complete scanlines per call.

   219 It is not possible to process part of a row at a time.  Scanlines are always

   220 processed top-to-bottom.  You can process an entire image in one call if you

   221 have it all in memory, but usually it's simplest to process one scanline at

   222 a time.

   223 

   224 For best results, source data values should have the precision specified by

   225 BITS_IN_JSAMPLE (normally 8 bits).  For instance, if you choose to compress

   226 data that's only 6 bits/channel, you should left-justify each value in a

   227 byte before passing it to the compressor.  If you need to compress data

   228 that has more than 8 bits/channel, compile with BITS_IN_JSAMPLE = 12.

   229 (See "Library compile-time options", later.)

   230 

   231 

   232 The data format returned by the decompressor is the same in all details,

   233 except that colormapped output is supported.  (Again, a JPEG file is never

   234 colormapped.  But you can ask the decompressor to perform on-the-fly color

   235 quantization to deliver colormapped output.)  If you request colormapped

   236 output then the returned data array contains a single JSAMPLE per pixel;

   237 its value is an index into a color map.  The color map is represented as

   238 a 2-D JSAMPARRAY in which each row holds the values of one color component,

   239 that is, colormap[i][j] is the value of the i'th color component for pixel

   240 value (map index) j.  Note that since the colormap indexes are stored in

   241 JSAMPLEs, the maximum number of colors is limited by the size of JSAMPLE

   242 (ie, at most 256 colors for an 8-bit JPEG library).

   243 

   244 

   245 Compression details

   246 -------------------

   247 

   248 Here we revisit the JPEG compression outline given in the overview.

   249 

   250 1. Allocate and initialize a JPEG compression object.

   251 

   252 A JPEG compression object is a "struct jpeg_compress_struct".  (It also has

   253 a bunch of subsidiary structures which are allocated via malloc(), but the

   254 application doesn't control those directly.)  This struct can be just a local

   255 variable in the calling routine, if a single routine is going to execute the

   256 whole JPEG compression sequence.  Otherwise it can be static or allocated

   257 from malloc().

   258 

   259 You will also need a structure representing a JPEG error handler.  The part

   260 of this that the library cares about is a "struct jpeg_error_mgr".  If you

   261 are providing your own error handler, you'll typically want to embed the

   262 jpeg_error_mgr struct in a larger structure; this is discussed later under

   263 "Error handling".  For now we'll assume you are just using the default error

   264 handler.  The default error handler will print JPEG error/warning messages

   265 on stderr, and it will call exit() if a fatal error occurs.

   266 

   267 You must initialize the error handler structure, store a pointer to it into

   268 the JPEG object's "err" field, and then call jpeg_create_compress() to

   269 initialize the rest of the JPEG object.

   270 

   271 Typical code for this step, if you are using the default error handler, is

   272 

   273 	struct jpeg_compress_struct cinfo;

   274 	struct jpeg_error_mgr jerr;

   275 	...

   276 	cinfo.err = jpeg_std_error(&jerr);

   277 	jpeg_create_compress(&cinfo);

   278 

   279 jpeg_create_compress allocates a small amount of memory, so it could fail

   280 if you are out of memory.  In that case it will exit via the error handler;

   281 that's why the error handler must be initialized first.

   282 

   283 

   284 2. Specify the destination for the compressed data (eg, a file).

   285 

   286 As previously mentioned, the JPEG library delivers compressed data to a

   287 "data destination" module.  The library includes one data destination

   288 module which knows how to write to a stdio stream.  You can use your own

   289 destination module if you want to do something else, as discussed later.

   290 

   291 If you use the standard destination module, you must open the target stdio

   292 stream beforehand.  Typical code for this step looks like:

   293 

   294 	FILE * outfile;

   295 	...

   296 	if ((outfile = fopen(filename, "wb")) == NULL) {

   297 	    fprintf(stderr, "can't open %s\n", filename);

   298 	    exit(1);

   299 	}

   300 	jpeg_stdio_dest(&cinfo, outfile);

   301 

   302 where the last line invokes the standard destination module.

   303 

   304 WARNING: it is critical that the binary compressed data be delivered to the

   305 output file unchanged.  On non-Unix systems the stdio library may perform

   306 newline translation or otherwise corrupt binary data.  To suppress this

   307 behavior, you may need to use a "b" option to fopen (as shown above), or use

   308 setmode() or another routine to put the stdio stream in binary mode.  See

   309 cjpeg.c and djpeg.c for code that has been found to work on many systems.

   310 

   311 You can select the data destination after setting other parameters (step 3),

   312 if that's more convenient.  You may not change the destination between

   313 calling jpeg_start_compress() and jpeg_finish_compress().

   314 

   315 

   316 3. Set parameters for compression, including image size & colorspace.

   317 

   318 You must supply information about the source image by setting the following

   319 fields in the JPEG object (cinfo structure):

   320 

   321 	image_width		Width of image, in pixels

   322 	image_height		Height of image, in pixels

   323 	input_components	Number of color channels (samples per pixel)

   324 	in_color_space		Color space of source image

   325 

   326 The image dimensions are, hopefully, obvious.  JPEG supports image dimensions

   327 of 1 to 64K pixels in either direction.  The input color space is typically

   328 RGB or grayscale, and input_components is 3 or 1 accordingly.  (See "Special

   329 color spaces", later, for more info.)  The in_color_space field must be

   330 assigned one of the J_COLOR_SPACE enum constants, typically JCS_RGB or

   331 JCS_GRAYSCALE.

   332 

   333 JPEG has a large number of compression parameters that determine how the

   334 image is encoded.  Most applications don't need or want to know about all

   335 these parameters.  You can set all the parameters to reasonable defaults by

   336 calling jpeg_set_defaults(); then, if there are particular values you want

   337 to change, you can do so after that.  The "Compression parameter selection"

   338 section tells about all the parameters.

   339 

   340 You must set in_color_space correctly before calling jpeg_set_defaults(),

   341 because the defaults depend on the source image colorspace.  However the

   342 other three source image parameters need not be valid until you call

   343 jpeg_start_compress().  There's no harm in calling jpeg_set_defaults() more

   344 than once, if that happens to be convenient.

   345 

   346 Typical code for a 24-bit RGB source image is

   347 

   348 	cinfo.image_width = Width; 	/* image width and height, in pixels */

   349 	cinfo.image_height = Height;

   350 	cinfo.input_components = 3;	/* # of color components per pixel */

   351 	cinfo.in_color_space = JCS_RGB; /* colorspace of input image */

   352 

   353 	jpeg_set_defaults(&cinfo);

   354 	/* Make optional parameter settings here */

   355 

   356 

   357 4. jpeg_start_compress(...);

   358 

   359 After you have established the data destination and set all the necessary

   360 source image info and other parameters, call jpeg_start_compress() to begin

   361 a compression cycle.  This will initialize internal state, allocate working

   362 storage, and emit the first few bytes of the JPEG datastream header.

   363 

   364 Typical code:

   365 

   366 	jpeg_start_compress(&cinfo, TRUE);

   367 

   368 The "TRUE" parameter ensures that a complete JPEG interchange datastream

   369 will be written.  This is appropriate in most cases.  If you think you might

   370 want to use an abbreviated datastream, read the section on abbreviated

   371 datastreams, below.

   372 

   373 Once you have called jpeg_start_compress(), you may not alter any JPEG

   374 parameters or other fields of the JPEG object until you have completed

   375 the compression cycle.

   376 

   377 

   378 5. while (scan lines remain to be written)

   379 	jpeg_write_scanlines(...);

   380 

   381 Now write all the required image data by calling jpeg_write_scanlines()

   382 one or more times.  You can pass one or more scanlines in each call, up

   383 to the total image height.  In most applications it is convenient to pass

   384 just one or a few scanlines at a time.  The expected format for the passed

   385 data is discussed under "Data formats", above.

   386 

   387 Image data should be written in top-to-bottom scanline order.  The JPEG spec

   388 contains some weasel wording about how top and bottom are application-defined

   389 terms (a curious interpretation of the English language...) but if you want

   390 your files to be compatible with everyone else's, you WILL use top-to-bottom

   391 order.  If the source data must be read in bottom-to-top order, you can use

   392 the JPEG library's virtual array mechanism to invert the data efficiently.

   393 Examples of this can be found in the sample application cjpeg.

   394 

   395 The library maintains a count of the number of scanlines written so far

   396 in the next_scanline field of the JPEG object.  Usually you can just use

   397 this variable as the loop counter, so that the loop test looks like

   398 "while (cinfo.next_scanline < cinfo.image_height)".

   399 

   400 Code for this step depends heavily on the way that you store the source data.

   401 example.c shows the following code for the case of a full-size 2-D source

   402 array containing 3-byte RGB pixels:

   403 

   404 	JSAMPROW row_pointer[1];	/* pointer to a single row */

   405 	int row_stride;			/* physical row width in buffer */

   406 

   407 	row_stride = image_width * 3;	/* JSAMPLEs per row in image_buffer */

   408 

   409 	while (cinfo.next_scanline < cinfo.image_height) {

   410 	    row_pointer[0] = & image_buffer[cinfo.next_scanline * row_stride];

   411 	    jpeg_write_scanlines(&cinfo, row_pointer, 1);

   412 	}

   413 

   414 jpeg_write_scanlines() returns the number of scanlines actually written.

   415 This will normally be equal to the number passed in, so you can usually

   416 ignore the return value.  It is different in just two cases:

   417   * If you try to write more scanlines than the declared image height,

   418     the additional scanlines are ignored.

   419   * If you use a suspending data destination manager, output buffer overrun

   420     will cause the compressor to return before accepting all the passed lines.

   421     This feature is discussed under "I/O suspension", below.  The normal

   422     stdio destination manager will NOT cause this to happen.

   423 In any case, the return value is the same as the change in the value of

   424 next_scanline.

   425 

   426 

   427 6. jpeg_finish_compress(...);

   428 

   429 After all the image data has been written, call jpeg_finish_compress() to

   430 complete the compression cycle.  This step is ESSENTIAL to ensure that the

   431 last bufferload of data is written to the data destination.

   432 jpeg_finish_compress() also releases working memory associated with the JPEG

   433 object.

   434 

   435 Typical code:

   436 

   437 	jpeg_finish_compress(&cinfo);

   438 

   439 If using the stdio destination manager, don't forget to close the output

   440 stdio stream (if necessary) afterwards.

   441 

   442 If you have requested a multi-pass operating mode, such as Huffman code

   443 optimization, jpeg_finish_compress() will perform the additional passes using

   444 data buffered by the first pass.  In this case jpeg_finish_compress() may take

   445 quite a while to complete.  With the default compression parameters, this will

   446 not happen.

   447 

   448 It is an error to call jpeg_finish_compress() before writing the necessary

   449 total number of scanlines.  If you wish to abort compression, call

   450 jpeg_abort() as discussed below.

   451 

   452 After completing a compression cycle, you may dispose of the JPEG object

   453 as discussed next, or you may use it to compress another image.  In that case

   454 return to step 2, 3, or 4 as appropriate.  If you do not change the

   455 destination manager, the new datastream will be written to the same target.

   456 If you do not change any JPEG parameters, the new datastream will be written

   457 with the same parameters as before.  Note that you can change the input image

   458 dimensions freely between cycles, but if you change the input colorspace, you

   459 should call jpeg_set_defaults() to adjust for the new colorspace; and then

   460 you'll need to repeat all of step 3.

   461 

   462 

   463 7. Release the JPEG compression object.

   464 

   465 When you are done with a JPEG compression object, destroy it by calling

   466 jpeg_destroy_compress().  This will free all subsidiary memory (regardless of

   467 the previous state of the object).  Or you can call jpeg_destroy(), which

   468 works for either compression or decompression objects --- this may be more

   469 convenient if you are sharing code between compression and decompression

   470 cases.  (Actually, these routines are equivalent except for the declared type

   471 of the passed pointer.  To avoid gripes from ANSI C compilers, jpeg_destroy()

   472 should be passed a j_common_ptr.)

   473 

   474 If you allocated the jpeg_compress_struct structure from malloc(), freeing

   475 it is your responsibility --- jpeg_destroy() won't.  Ditto for the error

   476 handler structure.

   477 

   478 Typical code:

   479 

   480 	jpeg_destroy_compress(&cinfo);

   481 

   482 

   483 8. Aborting.

   484 

   485 If you decide to abort a compression cycle before finishing, you can clean up

   486 in either of two ways:

   487 

   488 * If you don't need the JPEG object any more, just call

   489   jpeg_destroy_compress() or jpeg_destroy() to release memory.  This is

   490   legitimate at any point after calling jpeg_create_compress() --- in fact,

   491   it's safe even if jpeg_create_compress() fails.

   492 

   493 * If you want to re-use the JPEG object, call jpeg_abort_compress(), or call

   494   jpeg_abort() which works on both compression and decompression objects.

   495   This will return the object to an idle state, releasing any working memory.

   496   jpeg_abort() is allowed at any time after successful object creation.

   497 

   498 Note that cleaning up the data destination, if required, is your

   499 responsibility; neither of these routines will call term_destination().

   500 (See "Compressed data handling", below, for more about that.)

   501 

   502 jpeg_destroy() and jpeg_abort() are the only safe calls to make on a JPEG

   503 object that has reported an error by calling error_exit (see "Error handling"

   504 for more info).  The internal state of such an object is likely to be out of

   505 whack.  Either of these two routines will return the object to a known state.

   506 

   507 

   508 Decompression details

   509 ---------------------

   510 

   511 Here we revisit the JPEG decompression outline given in the overview.

   512 

   513 1. Allocate and initialize a JPEG decompression object.

   514 

   515 This is just like initialization for compression, as discussed above,

   516 except that the object is a "struct jpeg_decompress_struct" and you

   517 call jpeg_create_decompress().  Error handling is exactly the same.

   518 

   519 Typical code:

   520 

   521 	struct jpeg_decompress_struct cinfo;

   522 	struct jpeg_error_mgr jerr;

   523 	...

   524 	cinfo.err = jpeg_std_error(&jerr);

   525 	jpeg_create_decompress(&cinfo);

   526 

   527 (Both here and in the IJG code, we usually use variable name "cinfo" for

   528 both compression and decompression objects.)

   529 

   530 

   531 2. Specify the source of the compressed data (eg, a file).

   532 

   533 As previously mentioned, the JPEG library reads compressed data from a "data

   534 source" module.  The library includes one data source module which knows how

   535 to read from a stdio stream.  You can use your own source module if you want

   536 to do something else, as discussed later.

   537 

   538 If you use the standard source module, you must open the source stdio stream

   539 beforehand.  Typical code for this step looks like:

   540 

   541 	FILE * infile;

   542 	...

   543 	if ((infile = fopen(filename, "rb")) == NULL) {

   544 	    fprintf(stderr, "can't open %s\n", filename);

   545 	    exit(1);

   546 	}

   547 	jpeg_stdio_src(&cinfo, infile);

   548 

   549 where the last line invokes the standard source module.

   550 

   551 WARNING: it is critical that the binary compressed data be read unchanged.

   552 On non-Unix systems the stdio library may perform newline translation or

   553 otherwise corrupt binary data.  To suppress this behavior, you may need to use

   554 a "b" option to fopen (as shown above), or use setmode() or another routine to

   555 put the stdio stream in binary mode.  See cjpeg.c and djpeg.c for code that

   556 has been found to work on many systems.

   557 

   558 You may not change the data source between calling jpeg_read_header() and

   559 jpeg_finish_decompress().  If you wish to read a series of JPEG images from

   560 a single source file, you should repeat the jpeg_read_header() to

   561 jpeg_finish_decompress() sequence without reinitializing either the JPEG

   562 object or the data source module; this prevents buffered input data from

   563 being discarded.

   564 

   565 

   566 3. Call jpeg_read_header() to obtain image info.

   567 

   568 Typical code for this step is just

   569 

   570 	jpeg_read_header(&cinfo, TRUE);

   571 

   572 This will read the source datastream header markers, up to the beginning

   573 of the compressed data proper.  On return, the image dimensions and other

   574 info have been stored in the JPEG object.  The application may wish to

   575 consult this information before selecting decompression parameters.

   576 

   577 More complex code is necessary if

   578   * A suspending data source is used --- in that case jpeg_read_header()

   579     may return before it has read all the header data.  See "I/O suspension",

   580     below.  The normal stdio source manager will NOT cause this to happen.

   581   * Abbreviated JPEG files are to be processed --- see the section on

   582     abbreviated datastreams.  Standard applications that deal only in

   583     interchange JPEG files need not be concerned with this case either.

   584 

   585 It is permissible to stop at this point if you just wanted to find out the

   586 image dimensions and other header info for a JPEG file.  In that case,

   587 call jpeg_destroy() when you are done with the JPEG object, or call

   588 jpeg_abort() to return it to an idle state before selecting a new data

   589 source and reading another header.

   590 

   591 

   592 4. Set parameters for decompression.

   593 

   594 jpeg_read_header() sets appropriate default decompression parameters based on

   595 the properties of the image (in particular, its colorspace).  However, you

   596 may well want to alter these defaults before beginning the decompression.

   597 For example, the default is to produce full color output from a color file.

   598 If you want colormapped output you must ask for it.  Other options allow the

   599 returned image to be scaled and allow various speed/quality tradeoffs to be

   600 selected.  "Decompression parameter selection", below, gives details.

   601 

   602 If the defaults are appropriate, nothing need be done at this step.

   603 

   604 Note that all default values are set by each call to jpeg_read_header().

   605 If you reuse a decompression object, you cannot expect your parameter

   606 settings to be preserved across cycles, as you can for compression.

   607 You must set desired parameter values each time.

   608 

   609 

   610 5. jpeg_start_decompress(...);

   611 

   612 Once the parameter values are satisfactory, call jpeg_start_decompress() to

   613 begin decompression.  This will initialize internal state, allocate working

   614 memory, and prepare for returning data.

   615 

   616 Typical code is just

   617 

   618 	jpeg_start_decompress(&cinfo);

   619 

   620 If you have requested a multi-pass operating mode, such as 2-pass color

   621 quantization, jpeg_start_decompress() will do everything needed before data

   622 output can begin.  In this case jpeg_start_decompress() may take quite a while

   623 to complete.  With a single-scan (non progressive) JPEG file and default

   624 decompression parameters, this will not happen; jpeg_start_decompress() will

   625 return quickly.

   626 

   627 After this call, the final output image dimensions, including any requested

   628 scaling, are available in the JPEG object; so is the selected colormap, if

   629 colormapped output has been requested.  Useful fields include

   630 

   631 	output_width		image width and height, as scaled

   632 	output_height

   633 	out_color_components	# of color components in out_color_space

   634 	output_components	# of color components returned per pixel

   635 	colormap		the selected colormap, if any

   636 	actual_number_of_colors		number of entries in colormap

   637 

   638 output_components is 1 (a colormap index) when quantizing colors; otherwise it

   639 equals out_color_components.  It is the number of JSAMPLE values that will be

   640 emitted per pixel in the output arrays.

   641 

   642 Typically you will need to allocate data buffers to hold the incoming image.

   643 You will need output_width * output_components JSAMPLEs per scanline in your

   644 output buffer, and a total of output_height scanlines will be returned.

   645 

   646 Note: if you are using the JPEG library's internal memory manager to allocate

   647 data buffers (as djpeg does), then the manager's protocol requires that you

   648 request large buffers *before* calling jpeg_start_decompress().  This is a

   649 little tricky since the output_XXX fields are not normally valid then.  You

   650 can make them valid by calling jpeg_calc_output_dimensions() after setting the

   651 relevant parameters (scaling, output color space, and quantization flag).

   652 

   653 

   654 6. while (scan lines remain to be read)

   655 	jpeg_read_scanlines(...);

   656 

   657 Now you can read the decompressed image data by calling jpeg_read_scanlines()

   658 one or more times.  At each call, you pass in the maximum number of scanlines

   659 to be read (ie, the height of your working buffer); jpeg_read_scanlines()

   660 will return up to that many lines.  The return value is the number of lines

   661 actually read.  The format of the returned data is discussed under "Data

   662 formats", above.  Don't forget that grayscale and color JPEGs will return

   663 different data formats!

   664 

   665 Image data is returned in top-to-bottom scanline order.  If you must write

   666 out the image in bottom-to-top order, you can use the JPEG library's virtual

   667 array mechanism to invert the data efficiently.  Examples of this can be

   668 found in the sample application djpeg.

   669 

   670 The library maintains a count of the number of scanlines returned so far

   671 in the output_scanline field of the JPEG object.  Usually you can just use

   672 this variable as the loop counter, so that the loop test looks like

   673 "while (cinfo.output_scanline < cinfo.output_height)".  (Note that the test

   674 should NOT be against image_height, unless you never use scaling.  The

   675 image_height field is the height of the original unscaled image.)

   676 The return value always equals the change in the value of output_scanline.

   677 

   678 If you don't use a suspending data source, it is safe to assume that

   679 jpeg_read_scanlines() reads at least one scanline per call, until the

   680 bottom of the image has been reached.

   681 

   682 If you use a buffer larger than one scanline, it is NOT safe to assume that

   683 jpeg_read_scanlines() fills it.  (The current implementation returns only a

   684 few scanlines per call, no matter how large a buffer you pass.)  So you must

   685 always provide a loop that calls jpeg_read_scanlines() repeatedly until the

   686 whole image has been read.

   687 

   688 

   689 7. jpeg_finish_decompress(...);

   690 

   691 After all the image data has been read, call jpeg_finish_decompress() to

   692 complete the decompression cycle.  This causes working memory associated

   693 with the JPEG object to be released.

   694 

   695 Typical code:

   696 

   697 	jpeg_finish_decompress(&cinfo);

   698 

   699 If using the stdio source manager, don't forget to close the source stdio

   700 stream if necessary.

   701 

   702 It is an error to call jpeg_finish_decompress() before reading the correct

   703 total number of scanlines.  If you wish to abort decompression, call

   704 jpeg_abort() as discussed below.

   705 

   706 After completing a decompression cycle, you may dispose of the JPEG object as

   707 discussed next, or you may use it to decompress another image.  In that case

   708 return to step 2 or 3 as appropriate.  If you do not change the source

   709 manager, the next image will be read from the same source.

   710 

   711 

   712 8. Release the JPEG decompression object.

   713 

   714 When you are done with a JPEG decompression object, destroy it by calling

   715 jpeg_destroy_decompress() or jpeg_destroy().  The previous discussion of

   716 destroying compression objects applies here too.

   717 

   718 Typical code:

   719 

   720 	jpeg_destroy_decompress(&cinfo);

   721 

   722 

   723 9. Aborting.

   724 

   725 You can abort a decompression cycle by calling jpeg_destroy_decompress() or

   726 jpeg_destroy() if you don't need the JPEG object any more, or

   727 jpeg_abort_decompress() or jpeg_abort() if you want to reuse the object.

   728 The previous discussion of aborting compression cycles applies here too.

   729 

   730 

   731 Mechanics of usage: include files, linking, etc

   732 -----------------------------------------------

   733 

   734 Applications using the JPEG library should include the header file jpeglib.h

   735 to obtain declarations of data types and routines.  Before including

   736 jpeglib.h, include system headers that define at least the typedefs FILE and

   737 size_t.  On ANSI-conforming systems, including <stdio.h> is sufficient; on

   738 older Unix systems, you may need <sys/types.h> to define size_t.

   739 

   740 If the application needs to refer to individual JPEG library error codes, also

   741 include jerror.h to define those symbols.

   742 

   743 jpeglib.h indirectly includes the files jconfig.h and jmorecfg.h.  If you are

   744 installing the JPEG header files in a system directory, you will want to

   745 install all four files: jpeglib.h, jerror.h, jconfig.h, jmorecfg.h.

   746 

   747 The most convenient way to include the JPEG code into your executable program

   748 is to prepare a library file ("libjpeg.a", or a corresponding name on non-Unix

   749 machines) and reference it at your link step.  If you use only half of the

   750 library (only compression or only decompression), only that much code will be

   751 included from the library, unless your linker is hopelessly brain-damaged.

   752 The supplied makefiles build libjpeg.a automatically (see install.txt).

   753 

   754 While you can build the JPEG library as a shared library if the whim strikes

   755 you, we don't really recommend it.  The trouble with shared libraries is that

   756 at some point you'll probably try to substitute a new version of the library

   757 without recompiling the calling applications.  That generally doesn't work

   758 because the parameter struct declarations usually change with each new

   759 version.  In other words, the library's API is *not* guaranteed binary

   760 compatible across versions; we only try to ensure source-code compatibility.

   761 (In hindsight, it might have been smarter to hide the parameter structs from

   762 applications and introduce a ton of access functions instead.  Too late now,

   763 however.)

   764 

   765 On some systems your application may need to set up a signal handler to ensure

   766 that temporary files are deleted if the program is interrupted.  This is most

   767 critical if you are on MS-DOS and use the jmemdos.c memory manager back end;

   768 it will try to grab extended memory for temp files, and that space will NOT be

   769 freed automatically.  See cjpeg.c or djpeg.c for an example signal handler.

   770 

   771 It may be worth pointing out that the core JPEG library does not actually

   772 require the stdio library: only the default source/destination managers and

   773 error handler need it.  You can use the library in a stdio-less environment

   774 if you replace those modules and use jmemnobs.c (or another memory manager of

   775 your own devising).  More info about the minimum system library requirements

   776 may be found in jinclude.h.

   777 

   778 

   779 ADVANCED FEATURES

   780 =================

   781 

   782 Compression parameter selection

   783 -------------------------------

   784 

   785 This section describes all the optional parameters you can set for JPEG

   786 compression, as well as the "helper" routines provided to assist in this

   787 task.  Proper setting of some parameters requires detailed understanding

   788 of the JPEG standard; if you don't know what a parameter is for, it's best

   789 not to mess with it!  See REFERENCES in the README file for pointers to

   790 more info about JPEG.

   791 

   792 It's a good idea to call jpeg_set_defaults() first, even if you plan to set

   793 all the parameters; that way your code is more likely to work with future JPEG

   794 libraries that have additional parameters.  For the same reason, we recommend

   795 you use a helper routine where one is provided, in preference to twiddling

   796 cinfo fields directly.

   797 

   798 The helper routines are:

   799 

   800 jpeg_set_defaults (j_compress_ptr cinfo)

   801 	This routine sets all JPEG parameters to reasonable defaults, using

   802 	only the input image's color space (field in_color_space, which must

   803 	already be set in cinfo).  Many applications will only need to use

   804 	this routine and perhaps jpeg_set_quality().

   805 

   806 jpeg_set_colorspace (j_compress_ptr cinfo, J_COLOR_SPACE colorspace)

   807 	Sets the JPEG file's colorspace (field jpeg_color_space) as specified,

   808 	and sets other color-space-dependent parameters appropriately.  See

   809 	"Special color spaces", below, before using this.  A large number of

   810 	parameters, including all per-component parameters, are set by this

   811 	routine; if you want to twiddle individual parameters you should call

   812 	jpeg_set_colorspace() before rather than after.

   813 

   814 jpeg_default_colorspace (j_compress_ptr cinfo)

   815 	Selects an appropriate JPEG colorspace based on cinfo->in_color_space,

   816 	and calls jpeg_set_colorspace().  This is actually a subroutine of

   817 	jpeg_set_defaults().  It's broken out in case you want to change

   818 	just the colorspace-dependent JPEG parameters.

   819 

   820 jpeg_set_quality (j_compress_ptr cinfo, int quality, boolean force_baseline)

   821 	Constructs JPEG quantization tables appropriate for the indicated

   822 	quality setting.  The quality value is expressed on the 0..100 scale

   823 	recommended by IJG (cjpeg's "-quality" switch uses this routine).

   824 	Note that the exact mapping from quality values to tables may change

   825 	in future IJG releases as more is learned about DCT quantization.

   826 	If the force_baseline parameter is TRUE, then the quantization table

   827 	entries are constrained to the range 1..255 for full JPEG baseline

   828 	compatibility.  In the current implementation, this only makes a

   829 	difference for quality settings below 25, and it effectively prevents

   830 	very small/low quality files from being generated.  The IJG decoder

   831 	is capable of reading the non-baseline files generated at low quality

   832 	settings when force_baseline is FALSE, but other decoders may not be.

   833 

   834 jpeg_set_linear_quality (j_compress_ptr cinfo, int scale_factor,

   835 			 boolean force_baseline)

   836 	Same as jpeg_set_quality() except that the generated tables are the

   837 	sample tables given in the JPEC spec section K.1, multiplied by the

   838 	specified scale factor (which is expressed as a percentage; thus

   839 	scale_factor = 100 reproduces the spec's tables).  Note that larger

   840 	scale factors give lower quality.  This entry point is useful for

   841 	conforming to the Adobe PostScript DCT conventions, but we do not

   842 	recommend linear scaling as a user-visible quality scale otherwise.

   843 	force_baseline again constrains the computed table entries to 1..255.

   844 

   845 int jpeg_quality_scaling (int quality)

   846 	Converts a value on the IJG-recommended quality scale to a linear

   847 	scaling percentage.  Note that this routine may change or go away

   848 	in future releases --- IJG may choose to adopt a scaling method that

   849 	can't be expressed as a simple scalar multiplier, in which case the

   850 	premise of this routine collapses.  Caveat user.

   851 

   852 jpeg_default_qtables (j_compress_ptr cinfo, boolean force_baseline)

   853 	Set default quantization tables with linear q_scale_factor[] values

   854 	(see below).

   855 

   856 jpeg_add_quant_table (j_compress_ptr cinfo, int which_tbl,

   857 		      const unsigned int *basic_table,

   858 		      int scale_factor, boolean force_baseline)

   859 	Allows an arbitrary quantization table to be created.  which_tbl

   860 	indicates which table slot to fill.  basic_table points to an array

   861 	of 64 unsigned ints given in normal array order.  These values are

   862 	multiplied by scale_factor/100 and then clamped to the range 1..65535

   863 	(or to 1..255 if force_baseline is TRUE).

   864 	CAUTION: prior to library version 6a, jpeg_add_quant_table expected

   865 	the basic table to be given in JPEG zigzag order.  If you need to

   866 	write code that works with either older or newer versions of this

   867 	routine, you must check the library version number.  Something like

   868 	"#if JPEG_LIB_VERSION >= 61" is the right test.

   869 

   870 jpeg_simple_progression (j_compress_ptr cinfo)

   871 	Generates a default scan script for writing a progressive-JPEG file.

   872 	This is the recommended method of creating a progressive file,

   873 	unless you want to make a custom scan sequence.  You must ensure that

   874 	the JPEG color space is set correctly before calling this routine.

   875 

   876 

   877 Compression parameters (cinfo fields) include:

   878 

   879 J_DCT_METHOD dct_method

   880 	Selects the algorithm used for the DCT step.  Choices are:

   881 		JDCT_ISLOW: slow but accurate integer algorithm

   882 		JDCT_IFAST: faster, less accurate integer method

   883 		JDCT_FLOAT: floating-point method

   884 		JDCT_DEFAULT: default method (normally JDCT_ISLOW)

   885 		JDCT_FASTEST: fastest method (normally JDCT_IFAST)

   886 	The FLOAT method is very slightly more accurate than the ISLOW method,

   887 	but may give different results on different machines due to varying

   888 	roundoff behavior.  The integer methods should give the same results

   889 	on all machines.  On machines with sufficiently fast FP hardware, the

   890 	floating-point method may also be the fastest.  The IFAST method is

   891 	considerably less accurate than the other two; its use is not

   892 	recommended if high quality is a concern.  JDCT_DEFAULT and

   893 	JDCT_FASTEST are macros configurable by each installation.

   894 

   895 unsigned int scale_num, scale_denom

   896 	Scale the image by the fraction scale_num/scale_denom.  Default is

   897 	1/1, or no scaling.  Currently, the supported scaling ratios are

   898 	8/N with all N from 1 to 16.  (The library design allows for arbitrary

   899 	scaling ratios but this is not likely to be implemented any time soon.)

   900 

   901 J_COLOR_SPACE jpeg_color_space

   902 int num_components

   903 	The JPEG color space and corresponding number of components; see

   904 	"Special color spaces", below, for more info.  We recommend using

   905 	jpeg_set_color_space() if you want to change these.

   906 

   907 boolean optimize_coding

   908 	TRUE causes the compressor to compute optimal Huffman coding tables

   909 	for the image.  This requires an extra pass over the data and

   910 	therefore costs a good deal of space and time.  The default is

   911 	FALSE, which tells the compressor to use the supplied or default

   912 	Huffman tables.  In most cases optimal tables save only a few percent

   913 	of file size compared to the default tables.  Note that when this is

   914 	TRUE, you need not supply Huffman tables at all, and any you do

   915 	supply will be overwritten.

   916 

   917 unsigned int restart_interval

   918 int restart_in_rows

   919 	To emit restart markers in the JPEG file, set one of these nonzero.

   920 	Set restart_interval to specify the exact interval in MCU blocks.

   921 	Set restart_in_rows to specify the interval in MCU rows.  (If

   922 	restart_in_rows is not 0, then restart_interval is set after the

   923 	image width in MCUs is computed.)  Defaults are zero (no restarts).

   924 	One restart marker per MCU row is often a good choice.

   925 	NOTE: the overhead of restart markers is higher in grayscale JPEG

   926 	files than in color files, and MUCH higher in progressive JPEGs.

   927 	If you use restarts, you may want to use larger intervals in those

   928 	cases.

   929 

   930 const jpeg_scan_info * scan_info

   931 int num_scans

   932 	By default, scan_info is NULL; this causes the compressor to write a

   933 	single-scan sequential JPEG file.  If not NULL, scan_info points to

   934 	an array of scan definition records of length num_scans.  The

   935 	compressor will then write a JPEG file having one scan for each scan

   936 	definition record.  This is used to generate noninterleaved or

   937 	progressive JPEG files.  The library checks that the scan array

   938 	defines a valid JPEG scan sequence.  (jpeg_simple_progression creates

   939 	a suitable scan definition array for progressive JPEG.)  This is

   940 	discussed further under "Progressive JPEG support".

   941 

   942 boolean do_fancy_downsampling

   943 	If TRUE, use direct DCT scaling with DCT size > 8 for downsampling

   944 	of chroma components.

   945 	If FALSE, use only DCT size <= 8 and simple separate downsampling.

   946 	Default is TRUE.

   947 	For better image stability in multiple generation compression cycles

   948 	it is preferable that this value matches the corresponding

   949 	do_fancy_upsampling value in decompression.

   950 

   951 int smoothing_factor

   952 	If non-zero, the input image is smoothed; the value should be 1 for

   953 	minimal smoothing to 100 for maximum smoothing.  Consult jcsample.c

   954 	for details of the smoothing algorithm.  The default is zero.

   955 

   956 boolean write_JFIF_header

   957 	If TRUE, a JFIF APP0 marker is emitted.  jpeg_set_defaults() and

   958 	jpeg_set_colorspace() set this TRUE if a JFIF-legal JPEG color space

   959 	(ie, YCbCr or grayscale) is selected, otherwise FALSE.

   960 

   961 UINT8 JFIF_major_version

   962 UINT8 JFIF_minor_version

   963 	The version number to be written into the JFIF marker.

   964 	jpeg_set_defaults() initializes the version to 1.01 (major=minor=1).

   965 	You should set it to 1.02 (major=1, minor=2) if you plan to write

   966 	any JFIF 1.02 extension markers.

   967 

   968 UINT8 density_unit

   969 UINT16 X_density

   970 UINT16 Y_density

   971 	The resolution information to be written into the JFIF marker;

   972 	not used otherwise.  density_unit may be 0 for unknown,

   973 	1 for dots/inch, or 2 for dots/cm.  The default values are 0,1,1

   974 	indicating square pixels of unknown size.

   975 

   976 boolean write_Adobe_marker

   977 	If TRUE, an Adobe APP14 marker is emitted.  jpeg_set_defaults() and

   978 	jpeg_set_colorspace() set this TRUE if JPEG color space RGB, CMYK,

   979 	or YCCK is selected, otherwise FALSE.  It is generally a bad idea

   980 	to set both write_JFIF_header and write_Adobe_marker.  In fact,

   981 	you probably shouldn't change the default settings at all --- the

   982 	default behavior ensures that the JPEG file's color space can be

   983 	recognized by the decoder.

   984 

   985 JQUANT_TBL * quant_tbl_ptrs[NUM_QUANT_TBLS]

   986 	Pointers to coefficient quantization tables, one per table slot,

   987 	or NULL if no table is defined for a slot.  Usually these should

   988 	be set via one of the above helper routines; jpeg_add_quant_table()

   989 	is general enough to define any quantization table.  The other

   990 	routines will set up table slot 0 for luminance quality and table

   991 	slot 1 for chrominance.

   992 

   993 int q_scale_factor[NUM_QUANT_TBLS]

   994 	Linear quantization scaling factors (percentage, initialized 100)

   995 	for use with jpeg_default_qtables().

   996 	See rdswitch.c and cjpeg.c for an example of usage.

   997 	Note that the q_scale_factor[] fields are the "linear" scales, so you

   998 	have to convert from user-defined ratings via jpeg_quality_scaling().

   999 	Here is an example code which corresponds to cjpeg -quality 90,70:

  1000 

  1001 		jpeg_set_defaults(cinfo);

  1002 

  1003 		/* Set luminance quality 90. */

  1004 		cinfo->q_scale_factor[0] = jpeg_quality_scaling(90);

  1005 		/* Set chrominance quality 70. */

  1006 		cinfo->q_scale_factor[1] = jpeg_quality_scaling(70);

  1007 

  1008 		jpeg_default_qtables(cinfo, force_baseline);

  1009 

  1010 	CAUTION: You must also set 1x1 subsampling for efficient separate

  1011 	color quality selection, since the default value used by library

  1012 	is 2x2:

  1013 

  1014 		cinfo->comp_info[0].v_samp_factor = 1;

  1015 		cinfo->comp_info[0].h_samp_factor = 1;

  1016 

  1017 JHUFF_TBL * dc_huff_tbl_ptrs[NUM_HUFF_TBLS]

  1018 JHUFF_TBL * ac_huff_tbl_ptrs[NUM_HUFF_TBLS]

  1019 	Pointers to Huffman coding tables, one per table slot, or NULL if

  1020 	no table is defined for a slot.  Slots 0 and 1 are filled with the

  1021 	JPEG sample tables by jpeg_set_defaults().  If you need to allocate

  1022 	more table structures, jpeg_alloc_huff_table() may be used.

  1023 	Note that optimal Huffman tables can be computed for an image

  1024 	by setting optimize_coding, as discussed above; there's seldom

  1025 	any need to mess with providing your own Huffman tables.

  1026 

  1027 

  1028 The actual dimensions of the JPEG image that will be written to the file are

  1029 given by the following fields.  These are computed from the input image

  1030 dimensions and the compression parameters by jpeg_start_compress().  You can

  1031 also call jpeg_calc_jpeg_dimensions() to obtain the values that will result

  1032 from the current parameter settings.  This can be useful if you are trying

  1033 to pick a scaling ratio that will get close to a desired target size.

  1034 

  1035 JDIMENSION jpeg_width		Actual dimensions of output image.

  1036 JDIMENSION jpeg_height

  1037 

  1038 

  1039 Per-component parameters are stored in the struct cinfo.comp_info[i] for

  1040 component number i.  Note that components here refer to components of the

  1041 JPEG color space, *not* the source image color space.  A suitably large

  1042 comp_info[] array is allocated by jpeg_set_defaults(); if you choose not

  1043 to use that routine, it's up to you to allocate the array.

  1044 

  1045 int component_id

  1046 	The one-byte identifier code to be recorded in the JPEG file for

  1047 	this component.  For the standard color spaces, we recommend you

  1048 	leave the default values alone.

  1049 

  1050 int h_samp_factor

  1051 int v_samp_factor

  1052 	Horizontal and vertical sampling factors for the component; must

  1053 	be 1..4 according to the JPEG standard.  Note that larger sampling

  1054 	factors indicate a higher-resolution component; many people find

  1055 	this behavior quite unintuitive.  The default values are 2,2 for

  1056 	luminance components and 1,1 for chrominance components, except

  1057 	for grayscale where 1,1 is used.

  1058 

  1059 int quant_tbl_no

  1060 	Quantization table number for component.  The default value is

  1061 	0 for luminance components and 1 for chrominance components.

  1062 

  1063 int dc_tbl_no

  1064 int ac_tbl_no

  1065 	DC and AC entropy coding table numbers.  The default values are

  1066 	0 for luminance components and 1 for chrominance components.

  1067 

  1068 int component_index

  1069 	Must equal the component's index in comp_info[].  (Beginning in

  1070 	release v6, the compressor library will fill this in automatically;

  1071 	you don't have to.)

  1072 

  1073 

  1074 Decompression parameter selection

  1075 ---------------------------------

  1076 

  1077 Decompression parameter selection is somewhat simpler than compression

  1078 parameter selection, since all of the JPEG internal parameters are

  1079 recorded in the source file and need not be supplied by the application.

  1080 (Unless you are working with abbreviated files, in which case see

  1081 "Abbreviated datastreams", below.)  Decompression parameters control

  1082 the postprocessing done on the image to deliver it in a format suitable

  1083 for the application's use.  Many of the parameters control speed/quality

  1084 tradeoffs, in which faster decompression may be obtained at the price of

  1085 a poorer-quality image.  The defaults select the highest quality (slowest)

  1086 processing.

  1087 

  1088 The following fields in the JPEG object are set by jpeg_read_header() and

  1089 may be useful to the application in choosing decompression parameters:

  1090 

  1091 JDIMENSION image_width			Width and height of image

  1092 JDIMENSION image_height

  1093 int num_components			Number of color components

  1094 J_COLOR_SPACE jpeg_color_space		Colorspace of image

  1095 boolean saw_JFIF_marker			TRUE if a JFIF APP0 marker was seen

  1096   UINT8 JFIF_major_version		Version information from JFIF marker

  1097   UINT8 JFIF_minor_version

  1098   UINT8 density_unit			Resolution data from JFIF marker

  1099   UINT16 X_density

  1100   UINT16 Y_density

  1101 boolean saw_Adobe_marker		TRUE if an Adobe APP14 marker was seen

  1102   UINT8 Adobe_transform			Color transform code from Adobe marker

  1103 

  1104 The JPEG color space, unfortunately, is something of a guess since the JPEG

  1105 standard proper does not provide a way to record it.  In practice most files

  1106 adhere to the JFIF or Adobe conventions, and the decoder will recognize these

  1107 correctly.  See "Special color spaces", below, for more info.

  1108 

  1109 

  1110 The decompression parameters that determine the basic properties of the

  1111 returned image are:

  1112 

  1113 J_COLOR_SPACE out_color_space

  1114 	Output color space.  jpeg_read_header() sets an appropriate default

  1115 	based on jpeg_color_space; typically it will be RGB or grayscale.

  1116 	The application can change this field to request output in a different

  1117 	colorspace.  For example, set it to JCS_GRAYSCALE to get grayscale

  1118 	output from a color file.  (This is useful for previewing: grayscale

  1119 	output is faster than full color since the color components need not

  1120 	be processed.)  Note that not all possible color space transforms are

  1121 	currently implemented; you may need to extend jdcolor.c if you want an

  1122 	unusual conversion.

  1123 

  1124 unsigned int scale_num, scale_denom

  1125 	Scale the image by the fraction scale_num/scale_denom.  Currently,

  1126 	the supported scaling ratios are M/N with all M from 1 to 16, where

  1127 	N is the source DCT size, which is 8 for baseline JPEG.  (The library

  1128 	design allows for arbitrary scaling ratios but this is not likely

  1129 	to be implemented any time soon.)  The values are initialized by

  1130 	jpeg_read_header() with the source DCT size.  For baseline JPEG

  1131 	this is 8/8.  If you change only the scale_num value while leaving

  1132 	the other unchanged, then this specifies the DCT scaled size to be

  1133 	applied on the given input.  For baseline JPEG this is equivalent

  1134 	to M/8 scaling, since the source DCT size for baseline JPEG is 8.

  1135 	Smaller scaling ratios permit significantly faster decoding since