USING THE IJG JPEG LIBRARY
This file was part of the Independent JPEG Group's software:
-Copyright (C) 1994-2011, Thomas G. Lane, Guido Vollbeding.
-Modifications:
-Copyright (C) 2010, D. R. Commander.
-For conditions of distribution and use, see the accompanying README file.
+Copyright (C) 1994-2013, Thomas G. Lane, Guido Vollbeding.
+libjpeg-turbo Modifications:
+Copyright (C) 2010, 2014-2018, 2020, 2022, D. R. Commander.
+Copyright (C) 2015, Google, Inc.
+For conditions of distribution and use, see the accompanying README.ijg file.
This file describes how to use the IJG JPEG library within an application
program. Read it if you want to write a program that uses the library.
-The file example.c provides heavily commented skeleton code for calling the
+The file example.txt provides heavily commented skeleton code for calling the
JPEG library. Also see jpeglib.h (the include file to be used by application
programs) for full details about data structures and function parameter lists.
The library source code, of course, is the ultimate reference.
-----------------
Overview:
- Functions provided by the library
- Outline of typical usage
+ Functions provided by the library
+ Outline of typical usage
Basic library usage:
- Data formats
- Compression details
- Decompression details
- Mechanics of usage: include files, linking, etc
+ Data formats
+ Compression details
+ Decompression details
+ Partial image decompression
+ Mechanics of usage: include files, linking, etc
Advanced features:
- Compression parameter selection
- Decompression parameter selection
- Special color spaces
- Error handling
- Compressed data handling (source and destination managers)
- I/O suspension
- Progressive JPEG support
- Buffered-image mode
- Abbreviated datastreams and multiple images
- Special markers
- Raw (downsampled) image data
- Really raw data: DCT coefficients
- Progress monitoring
- Memory management
- Memory usage
- Library compile-time options
- Portability considerations
- Notes for MS-DOS implementors
+ Compression parameter selection
+ Decompression parameter selection
+ Special color spaces
+ Error handling
+ Compressed data handling (source and destination managers)
+ I/O suspension
+ Progressive JPEG support
+ Buffered-image mode
+ Abbreviated datastreams and multiple images
+ Special markers
+ ICC profiles
+ Raw (downsampled) image data
+ Really raw data: DCT coefficients
+ Progress monitoring
+ Memory management
+ Memory usage
+ Library compile-time options
+ Portability considerations
You should read at least the overview and basic usage sections before trying
to program with the library. The sections on advanced features can be read
the ISO JPEG standard; most baseline, extended-sequential, and progressive
JPEG processes are supported. (Our subset includes all features now in common
use.) Unsupported ISO options include:
- * Hierarchical storage
- * Lossless JPEG
- * DNL marker
- * Nonintegral subsampling ratios
+ * Hierarchical storage
+ * Lossless JPEG
+ * DNL marker
+ * Nonintegral subsampling ratios
We support both 8- and 12-bit data precision, but this is a compile-time
choice rather than a run-time choice; hence it is difficult to use both
precisions in a single application.
The rough outline of a JPEG compression operation is:
- Allocate and initialize a JPEG compression object
- Specify the destination for the compressed data (eg, a file)
- Set parameters for compression, including image size & colorspace
- jpeg_start_compress(...);
- while (scan lines remain to be written)
- jpeg_write_scanlines(...);
- jpeg_finish_compress(...);
- Release the JPEG compression object
+ Allocate and initialize a JPEG compression object
+ Specify the destination for the compressed data (eg, a file)
+ Set parameters for compression, including image size & colorspace
+ jpeg_start_compress(...);
+ while (scan lines remain to be written)
+ jpeg_write_scanlines(...);
+ jpeg_finish_compress(...);
+ Release the JPEG compression object
A JPEG compression object holds parameters and working state for the JPEG
library. We make creation/destruction of the object separate from starting
Similarly, the rough outline of a JPEG decompression operation is:
- Allocate and initialize a JPEG decompression object
- Specify the source of the compressed data (eg, a file)
- Call jpeg_read_header() to obtain image info
- Set parameters for decompression
- jpeg_start_decompress(...);
- while (scan lines remain to be read)
- jpeg_read_scanlines(...);
- jpeg_finish_decompress(...);
- Release the JPEG decompression object
+ Allocate and initialize a JPEG decompression object
+ Specify the source of the compressed data (eg, a file)
+ Call jpeg_read_header() to obtain image info
+ Set parameters for decompression
+ jpeg_start_decompress(...);
+ while (scan lines remain to be read)
+ jpeg_read_scanlines(...);
+ jpeg_finish_decompress(...);
+ Release the JPEG decompression object
This is comparable to the compression outline except that reading the
datastream header is a separate step. This is helpful because information
feed in a colormapped image by expanding it to full-color format. However
JPEG often doesn't work very well with source data that has been colormapped,
because of dithering noise. This is discussed in more detail in the JPEG FAQ
-and the other references mentioned in the README file.
+and the other references mentioned in the README.ijg file.
Pixels are stored by scanlines, with each scanline running from left to
right. The component values for each pixel are adjacent in the row; for
Typical code for this step, if you are using the default error handler, is
- struct jpeg_compress_struct cinfo;
- struct jpeg_error_mgr jerr;
- ...
- cinfo.err = jpeg_std_error(&jerr);
- jpeg_create_compress(&cinfo);
+ struct jpeg_compress_struct cinfo;
+ struct jpeg_error_mgr jerr;
+ ...
+ cinfo.err = jpeg_std_error(&jerr);
+ jpeg_create_compress(&cinfo);
jpeg_create_compress allocates a small amount of memory, so it could fail
if you are out of memory. In that case it will exit via the error handler;
If you use the standard destination module, you must open the target stdio
stream beforehand. Typical code for this step looks like:
- FILE * outfile;
- ...
- if ((outfile = fopen(filename, "wb")) == NULL) {
- fprintf(stderr, "can't open %s\n", filename);
- exit(1);
- }
- jpeg_stdio_dest(&cinfo, outfile);
+ FILE *outfile;
+ ...
+ if ((outfile = fopen(filename, "wb")) == NULL) {
+ fprintf(stderr, "can't open %s\n", filename);
+ exit(1);
+ }
+ jpeg_stdio_dest(&cinfo, outfile);
where the last line invokes the standard destination module.
You must supply information about the source image by setting the following
fields in the JPEG object (cinfo structure):
- image_width Width of image, in pixels
- image_height Height of image, in pixels
- input_components Number of color channels (samples per pixel)
- in_color_space Color space of source image
+ image_width Width of image, in pixels
+ image_height Height of image, in pixels
+ input_components Number of color channels (samples per pixel)
+ in_color_space Color space of source image
The image dimensions are, hopefully, obvious. JPEG supports image dimensions
of 1 to 64K pixels in either direction. The input color space is typically
Typical code for a 24-bit RGB source image is
- cinfo.image_width = Width; /* image width and height, in pixels */
- cinfo.image_height = Height;
- cinfo.input_components = 3; /* # of color components per pixel */
- cinfo.in_color_space = JCS_RGB; /* colorspace of input image */
+ cinfo.image_width = Width; /* image width and height, in pixels */
+ cinfo.image_height = Height;
+ cinfo.input_components = 3; /* # of color components per pixel */
+ cinfo.in_color_space = JCS_RGB; /* colorspace of input image */
- jpeg_set_defaults(&cinfo);
- /* Make optional parameter settings here */
+ jpeg_set_defaults(&cinfo);
+ /* Make optional parameter settings here */
4. jpeg_start_compress(...);
Typical code:
- jpeg_start_compress(&cinfo, TRUE);
+ jpeg_start_compress(&cinfo, TRUE);
The "TRUE" parameter ensures that a complete JPEG interchange datastream
will be written. This is appropriate in most cases. If you think you might
5. while (scan lines remain to be written)
- jpeg_write_scanlines(...);
+ jpeg_write_scanlines(...);
Now write all the required image data by calling jpeg_write_scanlines()
one or more times. You can pass one or more scanlines in each call, up
just one or a few scanlines at a time. The expected format for the passed
data is discussed under "Data formats", above.
-Image data should be written in top-to-bottom scanline order. The JPEG spec
-contains some weasel wording about how top and bottom are application-defined
-terms (a curious interpretation of the English language...) but if you want
-your files to be compatible with everyone else's, you WILL use top-to-bottom
-order. If the source data must be read in bottom-to-top order, you can use
-the JPEG library's virtual array mechanism to invert the data efficiently.
-Examples of this can be found in the sample application cjpeg.
+Image data should be written in top-to-bottom scanline order.
+Rec. ITU-T T.81 | ISO/IEC 10918-1 says, "Applications determine which edges of
+a source image are defined as top, bottom, left, and right." However, if you
+want your files to be compatible with everyone else's, then top-to-bottom order
+must be used. If the source data must be read in bottom-to-top order, then you
+can use the JPEG library's virtual array mechanism to invert the data
+efficiently. Examples of this can be found in the sample application cjpeg.
The library maintains a count of the number of scanlines written so far
in the next_scanline field of the JPEG object. Usually you can just use
"while (cinfo.next_scanline < cinfo.image_height)".
Code for this step depends heavily on the way that you store the source data.
-example.c shows the following code for the case of a full-size 2-D source
+example.txt shows the following code for the case of a full-size 2-D source
array containing 3-byte RGB pixels:
- JSAMPROW row_pointer[1]; /* pointer to a single row */
- int row_stride; /* physical row width in buffer */
+ JSAMPROW row_pointer[1]; /* pointer to a single row */
+ int row_stride; /* physical row width in buffer */
- row_stride = image_width * 3; /* JSAMPLEs per row in image_buffer */
+ row_stride = image_width * 3; /* JSAMPLEs per row in image_buffer */
- while (cinfo.next_scanline < cinfo.image_height) {
- row_pointer[0] = & image_buffer[cinfo.next_scanline * row_stride];
- jpeg_write_scanlines(&cinfo, row_pointer, 1);
- }
+ while (cinfo.next_scanline < cinfo.image_height) {
+ row_pointer[0] = &image_buffer[cinfo.next_scanline * row_stride];
+ jpeg_write_scanlines(&cinfo, row_pointer, 1);
+ }
jpeg_write_scanlines() returns the number of scanlines actually written.
This will normally be equal to the number passed in, so you can usually
Typical code:
- jpeg_finish_compress(&cinfo);
+ jpeg_finish_compress(&cinfo);
If using the stdio destination manager, don't forget to close the output
stdio stream (if necessary) afterwards.
Typical code:
- jpeg_destroy_compress(&cinfo);
+ jpeg_destroy_compress(&cinfo);
8. Aborting.
Typical code:
- struct jpeg_decompress_struct cinfo;
- struct jpeg_error_mgr jerr;
- ...
- cinfo.err = jpeg_std_error(&jerr);
- jpeg_create_decompress(&cinfo);
+ struct jpeg_decompress_struct cinfo;
+ struct jpeg_error_mgr jerr;
+ ...
+ cinfo.err = jpeg_std_error(&jerr);
+ jpeg_create_decompress(&cinfo);
(Both here and in the IJG code, we usually use variable name "cinfo" for
both compression and decompression objects.)
If you use the standard source module, you must open the source stdio stream
beforehand. Typical code for this step looks like:
- FILE * infile;
- ...
- if ((infile = fopen(filename, "rb")) == NULL) {
- fprintf(stderr, "can't open %s\n", filename);
- exit(1);
- }
- jpeg_stdio_src(&cinfo, infile);
+ FILE *infile;
+ ...
+ if ((infile = fopen(filename, "rb")) == NULL) {
+ fprintf(stderr, "can't open %s\n", filename);
+ exit(1);
+ }
+ jpeg_stdio_src(&cinfo, infile);
where the last line invokes the standard source module.
Typical code for this step is just
- jpeg_read_header(&cinfo, TRUE);
+ jpeg_read_header(&cinfo, TRUE);
This will read the source datastream header markers, up to the beginning
of the compressed data proper. On return, the image dimensions and other
Typical code is just
- jpeg_start_decompress(&cinfo);
+ jpeg_start_decompress(&cinfo);
If you have requested a multi-pass operating mode, such as 2-pass color
quantization, jpeg_start_decompress() will do everything needed before data
scaling, are available in the JPEG object; so is the selected colormap, if
colormapped output has been requested. Useful fields include
- output_width image width and height, as scaled
- output_height
- out_color_components # of color components in out_color_space
- output_components # of color components returned per pixel
- colormap the selected colormap, if any
- actual_number_of_colors number of entries in colormap
+ output_width image width and height, as scaled
+ output_height
+ out_color_components # of color components in out_color_space
+ output_components # of color components returned per pixel
+ colormap the selected colormap, if any
+ actual_number_of_colors number of entries in colormap
output_components is 1 (a colormap index) when quantizing colors; otherwise it
equals out_color_components. It is the number of JSAMPLE values that will be
6. while (scan lines remain to be read)
- jpeg_read_scanlines(...);
+ jpeg_read_scanlines(...);
Now you can read the decompressed image data by calling jpeg_read_scanlines()
one or more times. At each call, you pass in the maximum number of scanlines
Typical code:
- jpeg_finish_decompress(&cinfo);
+ jpeg_finish_decompress(&cinfo);
If using the stdio source manager, don't forget to close the source stdio
stream if necessary.
Typical code:
- jpeg_destroy_decompress(&cinfo);
+ jpeg_destroy_decompress(&cinfo);
9. Aborting.
The previous discussion of aborting compression cycles applies here too.
+Partial image decompression
+---------------------------
+
+Partial image decompression is convenient for performance-critical applications
+that wish to view only a portion of a large JPEG image without decompressing
+the whole thing. It it also useful in memory-constrained environments (such as
+on mobile devices.) This library provides the following functions to support
+partial image decompression:
+
+1. Skipping rows when decompressing
+
+ jpeg_skip_scanlines(j_decompress_ptr cinfo, JDIMENSION num_lines);
+
+This function provides application programmers with the ability to skip over
+multiple rows in the JPEG image.
+
+Suspending data sources are not supported by this function. Calling
+jpeg_skip_scanlines() with a suspending data source will result in undefined
+behavior. Two-pass color quantization is also not supported by this function.
+Calling jpeg_skip_scanlines() with two-pass color quantization enabled will
+result in an error.
+
+jpeg_skip_scanlines() will not allow skipping past the bottom of the image. If
+the value of num_lines is large enough to skip past the bottom of the image,
+then the function will skip to the end of the image instead.
+
+If the value of num_lines is valid, then jpeg_skip_scanlines() will always
+skip all of the input rows requested. There is no need to inspect the return
+value of the function in that case.
+
+Best results will be achieved by calling jpeg_skip_scanlines() for large chunks
+of rows. The function should be viewed as a way to quickly jump to a
+particular vertical offset in the JPEG image in order to decode a subset of the
+image. Used in this manner, it will provide significant performance
+improvements.
+
+Calling jpeg_skip_scanlines() for small values of num_lines has several
+potential drawbacks:
+ 1) JPEG decompression occurs in blocks, so if jpeg_skip_scanlines() is
+ called from the middle of a decompression block, then it is likely that
+ much of the decompression work has already been done for the first
+ couple of rows that need to be skipped.
+ 2) When this function returns, it must leave the decompressor in a state
+ such that it is ready to read the next line. This may involve
+ decompressing a block that must be partially skipped.
+These issues are especially tricky for cases in which upsampling requires
+context rows. In the worst case, jpeg_skip_scanlines() will perform similarly
+to jpeg_read_scanlines() (since it will actually call jpeg_read_scanlines().)
+
+2. Decompressing partial scanlines
+
+ jpeg_crop_scanline (j_decompress_ptr cinfo, JDIMENSION *xoffset,
+ JDIMENSION *width)
+
+This function provides application programmers with the ability to decompress
+only a portion of each row in the JPEG image. It must be called after
+jpeg_start_decompress() and before any calls to jpeg_read_scanlines() or
+jpeg_skip_scanlines().
+
+If xoffset and width do not form a valid subset of the image row, then this
+function will generate an error. Note that if the output image is scaled, then
+xoffset and width are relative to the scaled image dimensions.
+
+xoffset and width are passed by reference because xoffset must fall on an iMCU
+boundary. If it doesn't, then it will be moved left to the nearest iMCU
+boundary, and width will be increased accordingly. If the calling program does
+not like the adjusted values of xoffset and width, then it can call
+jpeg_crop_scanline() again with new values (for instance, if it wants to move
+xoffset to the nearest iMCU boundary to the right instead of to the left.)
+
+After calling this function, cinfo->output_width will be set to the adjusted
+width. This value should be used when allocating an output buffer to pass to
+jpeg_read_scanlines().
+
+The output image from a partial-width decompression will be identical to the
+corresponding image region from a full decode, with one exception: The "fancy"
+(smooth) h2v2 (4:2:0) and h2v1 (4:2:2) upsampling algorithms fill in the
+missing chroma components by averaging the chroma components from neighboring
+pixels, except on the right and left edges of the image (where there are no
+neighboring pixels.) When performing a partial-width decompression, these
+"fancy" upsampling algorithms may treat the left and right edges of the partial
+image region as if they are the left and right edges of the image, meaning that
+the upsampling algorithm may be simplified. The result is that the pixels on
+the left or right edge of the partial image may not be exactly identical to the
+corresponding pixels in the original image.
+
+
Mechanics of usage: include files, linking, etc
-----------------------------------------------
machines) and reference it at your link step. If you use only half of the
library (only compression or only decompression), only that much code will be
included from the library, unless your linker is hopelessly brain-damaged.
-The supplied makefiles build libjpeg.a automatically (see install.txt).
-
-While you can build the JPEG library as a shared library if the whim strikes
-you, we don't really recommend it. The trouble with shared libraries is that
-at some point you'll probably try to substitute a new version of the library
-without recompiling the calling applications. That generally doesn't work
-because the parameter struct declarations usually change with each new
-version. In other words, the library's API is *not* guaranteed binary
-compatible across versions; we only try to ensure source-code compatibility.
-(In hindsight, it might have been smarter to hide the parameter structs from
-applications and introduce a ton of access functions instead. Too late now,
-however.)
-
-On some systems your application may need to set up a signal handler to ensure
-that temporary files are deleted if the program is interrupted. This is most
-critical if you are on MS-DOS and use the jmemdos.c memory manager back end;
-it will try to grab extended memory for temp files, and that space will NOT be
-freed automatically. See cjpeg.c or djpeg.c for an example signal handler.
+The supplied build system builds libjpeg.a automatically.
It may be worth pointing out that the core JPEG library does not actually
require the stdio library: only the default source/destination managers and
compression, as well as the "helper" routines provided to assist in this
task. Proper setting of some parameters requires detailed understanding
of the JPEG standard; if you don't know what a parameter is for, it's best
-not to mess with it! See REFERENCES in the README file for pointers to
+not to mess with it! See REFERENCES in the README.ijg file for pointers to
more info about JPEG.
It's a good idea to call jpeg_set_defaults() first, even if you plan to set
The helper routines are:
jpeg_set_defaults (j_compress_ptr cinfo)
- This routine sets all JPEG parameters to reasonable defaults, using
- only the input image's color space (field in_color_space, which must
- already be set in cinfo). Many applications will only need to use
- this routine and perhaps jpeg_set_quality().
+ This routine sets all JPEG parameters to reasonable defaults, using
+ only the input image's color space (field in_color_space, which must
+ already be set in cinfo). Many applications will only need to use
+ this routine and perhaps jpeg_set_quality().
jpeg_set_colorspace (j_compress_ptr cinfo, J_COLOR_SPACE colorspace)
- Sets the JPEG file's colorspace (field jpeg_color_space) as specified,
- and sets other color-space-dependent parameters appropriately. See
- "Special color spaces", below, before using this. A large number of
- parameters, including all per-component parameters, are set by this
- routine; if you want to twiddle individual parameters you should call
- jpeg_set_colorspace() before rather than after.
+ Sets the JPEG file's colorspace (field jpeg_color_space) as specified,
+ and sets other color-space-dependent parameters appropriately. See
+ "Special color spaces", below, before using this. A large number of
+ parameters, including all per-component parameters, are set by this
+ routine; if you want to twiddle individual parameters you should call
+ jpeg_set_colorspace() before rather than after.
jpeg_default_colorspace (j_compress_ptr cinfo)
- Selects an appropriate JPEG colorspace based on cinfo->in_color_space,
- and calls jpeg_set_colorspace(). This is actually a subroutine of
- jpeg_set_defaults(). It's broken out in case you want to change
- just the colorspace-dependent JPEG parameters.
+ Selects an appropriate JPEG colorspace based on cinfo->in_color_space,
+ and calls jpeg_set_colorspace(). This is actually a subroutine of
+ jpeg_set_defaults(). It's broken out in case you want to change
+ just the colorspace-dependent JPEG parameters.
jpeg_set_quality (j_compress_ptr cinfo, int quality, boolean force_baseline)
- Constructs JPEG quantization tables appropriate for the indicated
- quality setting. The quality value is expressed on the 0..100 scale
- recommended by IJG (cjpeg's "-quality" switch uses this routine).
- Note that the exact mapping from quality values to tables may change
- in future IJG releases as more is learned about DCT quantization.
- If the force_baseline parameter is TRUE, then the quantization table
- entries are constrained to the range 1..255 for full JPEG baseline
- compatibility. In the current implementation, this only makes a
- difference for quality settings below 25, and it effectively prevents
- very small/low quality files from being generated. The IJG decoder
- is capable of reading the non-baseline files generated at low quality
- settings when force_baseline is FALSE, but other decoders may not be.
+ Constructs JPEG quantization tables appropriate for the indicated
+ quality setting. The quality value is expressed on the 0..100 scale
+ recommended by IJG (cjpeg's "-quality" switch uses this routine).
+ Note that the exact mapping from quality values to tables may change
+ in future IJG releases as more is learned about DCT quantization.
+ If the force_baseline parameter is TRUE, then the quantization table
+ entries are constrained to the range 1..255 for full JPEG baseline
+ compatibility. In the current implementation, this only makes a
+ difference for quality settings below 25, and it effectively prevents
+ very small/low quality files from being generated. The IJG decoder
+ is capable of reading the non-baseline files generated at low quality
+ settings when force_baseline is FALSE, but other decoders may not be.
jpeg_set_linear_quality (j_compress_ptr cinfo, int scale_factor,
- boolean force_baseline)
- Same as jpeg_set_quality() except that the generated tables are the
- sample tables given in the JPEC spec section K.1, multiplied by the
- specified scale factor (which is expressed as a percentage; thus
- scale_factor = 100 reproduces the spec's tables). Note that larger
- scale factors give lower quality. This entry point is useful for
- conforming to the Adobe PostScript DCT conventions, but we do not
- recommend linear scaling as a user-visible quality scale otherwise.
- force_baseline again constrains the computed table entries to 1..255.
+ boolean force_baseline)
+ Same as jpeg_set_quality() except that the generated tables are the
+ sample tables given in Annex K (Clause K.1) of
+ Rec. ITU-T T.81 (1992) | ISO/IEC 10918-1:1994, multiplied by the
+ specified scale factor (which is expressed as a percentage; thus
+ scale_factor = 100 reproduces the spec's tables). Note that larger
+ scale factors give lower quality. This entry point is useful for
+ conforming to the Adobe PostScript DCT conventions, but we do not
+ recommend linear scaling as a user-visible quality scale otherwise.
+ force_baseline again constrains the computed table entries to 1..255.
int jpeg_quality_scaling (int quality)
- Converts a value on the IJG-recommended quality scale to a linear
- scaling percentage. Note that this routine may change or go away
- in future releases --- IJG may choose to adopt a scaling method that
- can't be expressed as a simple scalar multiplier, in which case the
- premise of this routine collapses. Caveat user.
+ Converts a value on the IJG-recommended quality scale to a linear
+ scaling percentage. Note that this routine may change or go away
+ in future releases --- IJG may choose to adopt a scaling method that
+ can't be expressed as a simple scalar multiplier, in which case the
+ premise of this routine collapses. Caveat user.
jpeg_default_qtables (j_compress_ptr cinfo, boolean force_baseline)
- [libjpeg v7+ API/ABI emulation only]
- Set default quantization tables with linear q_scale_factor[] values
- (see below).
+ [libjpeg v7+ API/ABI emulation only]
+ Set default quantization tables with linear q_scale_factor[] values
+ (see below).
jpeg_add_quant_table (j_compress_ptr cinfo, int which_tbl,
- const unsigned int *basic_table,
- int scale_factor, boolean force_baseline)
- Allows an arbitrary quantization table to be created. which_tbl
- indicates which table slot to fill. basic_table points to an array
- of 64 unsigned ints given in normal array order. These values are
- multiplied by scale_factor/100 and then clamped to the range 1..65535
- (or to 1..255 if force_baseline is TRUE).
- CAUTION: prior to library version 6a, jpeg_add_quant_table expected
- the basic table to be given in JPEG zigzag order. If you need to
- write code that works with either older or newer versions of this
- routine, you must check the library version number. Something like
- "#if JPEG_LIB_VERSION >= 61" is the right test.
+ const unsigned int *basic_table,
+ int scale_factor, boolean force_baseline)
+ Allows an arbitrary quantization table to be created. which_tbl
+ indicates which table slot to fill. basic_table points to an array
+ of 64 unsigned ints given in normal array order. These values are
+ multiplied by scale_factor/100 and then clamped to the range 1..65535
+ (or to 1..255 if force_baseline is TRUE).
+ CAUTION: prior to library version 6a, jpeg_add_quant_table expected
+ the basic table to be given in JPEG zigzag order. If you need to
+ write code that works with either older or newer versions of this
+ routine, you must check the library version number. Something like
+ "#if JPEG_LIB_VERSION >= 61" is the right test.
jpeg_simple_progression (j_compress_ptr cinfo)
- Generates a default scan script for writing a progressive-JPEG file.
- This is the recommended method of creating a progressive file,
- unless you want to make a custom scan sequence. You must ensure that
- the JPEG color space is set correctly before calling this routine.
+ Generates a default scan script for writing a progressive-JPEG file.
+ This is the recommended method of creating a progressive file,
+ unless you want to make a custom scan sequence. You must ensure that
+ the JPEG color space is set correctly before calling this routine.
Compression parameters (cinfo fields) include:
+boolean arith_code
+ If TRUE, use arithmetic coding.
+ If FALSE, use Huffman coding.
+
J_DCT_METHOD dct_method
- Selects the algorithm used for the DCT step. Choices are:
- JDCT_ISLOW: slow but accurate integer algorithm
- JDCT_IFAST: faster, less accurate integer method
- JDCT_FLOAT: floating-point method
- JDCT_DEFAULT: default method (normally JDCT_ISLOW)
- JDCT_FASTEST: fastest method (normally JDCT_IFAST)
- The FLOAT method is very slightly more accurate than the ISLOW method,
- but may give different results on different machines due to varying
- roundoff behavior. The integer methods should give the same results
- on all machines. On machines with sufficiently fast FP hardware, the
- floating-point method may also be the fastest. The IFAST method is
- considerably less accurate than the other two; its use is not
- recommended if high quality is a concern. JDCT_DEFAULT and
- JDCT_FASTEST are macros configurable by each installation.
+ Selects the algorithm used for the DCT step. Choices are:
+ JDCT_ISLOW: accurate integer method
+ JDCT_IFAST: less accurate integer method [legacy feature]
+ JDCT_FLOAT: floating-point method [legacy feature]
+ JDCT_DEFAULT: default method (normally JDCT_ISLOW)
+ JDCT_FASTEST: fastest method (normally JDCT_IFAST)
+ When the Independent JPEG Group's software was first released in 1991,
+ the compression time for a 1-megapixel JPEG image on a mainstream PC
+ was measured in minutes. Thus, JDCT_IFAST provided noticeable
+ performance benefits. On modern CPUs running libjpeg-turbo, however,
+ the compression time for a 1-megapixel JPEG image is measured in
+ milliseconds, and thus the performance benefits of JDCT_IFAST are much
+ less noticeable. On modern x86/x86-64 CPUs that support AVX2
+ instructions, JDCT_IFAST and JDCT_ISLOW have similar performance. On
+ other types of CPUs, JDCT_IFAST is generally about 5-15% faster than
+ JDCT_ISLOW.
+
+ For quality levels of 90 and below, there should be little or no
+ perceptible quality difference between the two algorithms. For quality
+ levels above 90, however, the difference between JDCT_IFAST and
+ JDCT_ISLOW becomes more pronounced. With quality=97, for instance,
+ JDCT_IFAST incurs generally about a 1-3 dB loss in PSNR relative to
+ JDCT_ISLOW, but this can be larger for some images. Do not use
+ JDCT_IFAST with quality levels above 97. The algorithm often
+ degenerates at quality=98 and above and can actually produce a more
+ lossy image than if lower quality levels had been used. Also, in
+ libjpeg-turbo, JDCT_IFAST is not fully accelerated for quality levels
+ above 97, so it will be slower than JDCT_ISLOW.
+
+ JDCT_FLOAT does not produce significantly more accurate results than
+ JDCT_ISLOW, and it is much slower. JDCT_FLOAT may also give different
+ results on different machines due to varying roundoff behavior, whereas
+ the integer methods should give the same results on all machines.
J_COLOR_SPACE jpeg_color_space
int num_components
- The JPEG color space and corresponding number of components; see
- "Special color spaces", below, for more info. We recommend using
- jpeg_set_color_space() if you want to change these.
+ The JPEG color space and corresponding number of components; see
+ "Special color spaces", below, for more info. We recommend using
+ jpeg_set_color_space() if you want to change these.
boolean optimize_coding
- TRUE causes the compressor to compute optimal Huffman coding tables
- for the image. This requires an extra pass over the data and
- therefore costs a good deal of space and time. The default is
- FALSE, which tells the compressor to use the supplied or default
- Huffman tables. In most cases optimal tables save only a few percent
- of file size compared to the default tables. Note that when this is
- TRUE, you need not supply Huffman tables at all, and any you do
- supply will be overwritten.
+ TRUE causes the compressor to compute optimal Huffman coding tables
+ for the image. This requires an extra pass over the data and
+ therefore costs a good deal of space and time. The default is
+ FALSE, which tells the compressor to use the supplied or default
+ Huffman tables. In most cases optimal tables save only a few percent
+ of file size compared to the default tables. Note that when this is
+ TRUE, you need not supply Huffman tables at all, and any you do
+ supply will be overwritten.
unsigned int restart_interval
int restart_in_rows
- To emit restart markers in the JPEG file, set one of these nonzero.
- Set restart_interval to specify the exact interval in MCU blocks.
- Set restart_in_rows to specify the interval in MCU rows. (If
- restart_in_rows is not 0, then restart_interval is set after the
- image width in MCUs is computed.) Defaults are zero (no restarts).
- One restart marker per MCU row is often a good choice.
- NOTE: the overhead of restart markers is higher in grayscale JPEG
- files than in color files, and MUCH higher in progressive JPEGs.
- If you use restarts, you may want to use larger intervals in those
- cases.
-
-const jpeg_scan_info * scan_info
+ To emit restart markers in the JPEG file, set one of these nonzero.
+ Set restart_interval to specify the exact interval in MCU blocks.
+ Set restart_in_rows to specify the interval in MCU rows. (If
+ restart_in_rows is not 0, then restart_interval is set after the
+ image width in MCUs is computed.) Defaults are zero (no restarts).
+ One restart marker per MCU row is often a good choice.
+ NOTE: the overhead of restart markers is higher in grayscale JPEG
+ files than in color files, and MUCH higher in progressive JPEGs.
+ If you use restarts, you may want to use larger intervals in those
+ cases.
+
+const jpeg_scan_info *scan_info
int num_scans
- By default, scan_info is NULL; this causes the compressor to write a
- single-scan sequential JPEG file. If not NULL, scan_info points to
- an array of scan definition records of length num_scans. The
- compressor will then write a JPEG file having one scan for each scan
- definition record. This is used to generate noninterleaved or
- progressive JPEG files. The library checks that the scan array
- defines a valid JPEG scan sequence. (jpeg_simple_progression creates
- a suitable scan definition array for progressive JPEG.) This is
- discussed further under "Progressive JPEG support".
+ By default, scan_info is NULL; this causes the compressor to write a
+ single-scan sequential JPEG file. If not NULL, scan_info points to
+ an array of scan definition records of length num_scans. The
+ compressor will then write a JPEG file having one scan for each scan
+ definition record. This is used to generate noninterleaved or
+ progressive JPEG files. The library checks that the scan array
+ defines a valid JPEG scan sequence. (jpeg_simple_progression creates
+ a suitable scan definition array for progressive JPEG.) This is
+ discussed further under "Progressive JPEG support".
int smoothing_factor
- If non-zero, the input image is smoothed; the value should be 1 for
- minimal smoothing to 100 for maximum smoothing. Consult jcsample.c
- for details of the smoothing algorithm. The default is zero.
+ If non-zero, the input image is smoothed; the value should be 1 for
+ minimal smoothing to 100 for maximum smoothing. Consult jcsample.c
+ for details of the smoothing algorithm. The default is zero.
boolean write_JFIF_header
- If TRUE, a JFIF APP0 marker is emitted. jpeg_set_defaults() and
- jpeg_set_colorspace() set this TRUE if a JFIF-legal JPEG color space
- (ie, YCbCr or grayscale) is selected, otherwise FALSE.
+ If TRUE, a JFIF APP0 marker is emitted. jpeg_set_defaults() and
+ jpeg_set_colorspace() set this TRUE if a JFIF-legal JPEG color space
+ (ie, YCbCr or grayscale) is selected, otherwise FALSE.
UINT8 JFIF_major_version
UINT8 JFIF_minor_version
- The version number to be written into the JFIF marker.
- jpeg_set_defaults() initializes the version to 1.01 (major=minor=1).
- You should set it to 1.02 (major=1, minor=2) if you plan to write
- any JFIF 1.02 extension markers.
+ The version number to be written into the JFIF marker.
+ jpeg_set_defaults() initializes the version to 1.01 (major=minor=1).
+ You should set it to 1.02 (major=1, minor=2) if you plan to write
+ any JFIF 1.02 extension markers.
UINT8 density_unit
UINT16 X_density
UINT16 Y_density
- The resolution information to be written into the JFIF marker;
- not used otherwise. density_unit may be 0 for unknown,
- 1 for dots/inch, or 2 for dots/cm. The default values are 0,1,1
- indicating square pixels of unknown size.
+ The resolution information to be written into the JFIF marker;
+ not used otherwise. density_unit may be 0 for unknown,
+ 1 for dots/inch, or 2 for dots/cm. The default values are 0,1,1
+ indicating square pixels of unknown size.
boolean write_Adobe_marker
- If TRUE, an Adobe APP14 marker is emitted. jpeg_set_defaults() and
- jpeg_set_colorspace() set this TRUE if JPEG color space RGB, CMYK,
- or YCCK is selected, otherwise FALSE. It is generally a bad idea
- to set both write_JFIF_header and write_Adobe_marker. In fact,
- you probably shouldn't change the default settings at all --- the
- default behavior ensures that the JPEG file's color space can be
- recognized by the decoder.
-
-JQUANT_TBL * quant_tbl_ptrs[NUM_QUANT_TBLS]
- Pointers to coefficient quantization tables, one per table slot,
- or NULL if no table is defined for a slot. Usually these should
- be set via one of the above helper routines; jpeg_add_quant_table()
- is general enough to define any quantization table. The other
- routines will set up table slot 0 for luminance quality and table
- slot 1 for chrominance.
+ If TRUE, an Adobe APP14 marker is emitted. jpeg_set_defaults() and
+ jpeg_set_colorspace() set this TRUE if JPEG color space RGB, CMYK,
+ or YCCK is selected, otherwise FALSE. It is generally a bad idea
+ to set both write_JFIF_header and write_Adobe_marker. In fact,
+ you probably shouldn't change the default settings at all --- the
+ default behavior ensures that the JPEG file's color space can be
+ recognized by the decoder.
+
+JQUANT_TBL *quant_tbl_ptrs[NUM_QUANT_TBLS]
+ Pointers to coefficient quantization tables, one per table slot,
+ or NULL if no table is defined for a slot. Usually these should
+ be set via one of the above helper routines; jpeg_add_quant_table()
+ is general enough to define any quantization table. The other
+ routines will set up table slot 0 for luminance quality and table
+ slot 1 for chrominance.
int q_scale_factor[NUM_QUANT_TBLS]
- [libjpeg v7+ API/ABI emulation only]
- Linear quantization scaling factors (0-100, default 100)
- for use with jpeg_default_qtables().
- See rdswitch.c and cjpeg.c for an example of usage.
- Note that the q_scale_factor[] values use "linear" scales, so JPEG
- quality levels chosen by the user must be converted to these scales
- using jpeg_quality_scaling(). Here is an example that corresponds to
- cjpeg -quality 90,70:
-
- jpeg_set_defaults(cinfo);
-
- /* Set luminance quality 90. */
- cinfo->q_scale_factor[0] = jpeg_quality_scaling(90);
- /* Set chrominance quality 70. */
- cinfo->q_scale_factor[1] = jpeg_quality_scaling(70);
-
- jpeg_default_qtables(cinfo, force_baseline);
-
- CAUTION: Setting separate quality levels for chrominance and luminance
- is mainly only useful if chrominance subsampling is disabled. 2x2
- chrominance subsampling (AKA "4:2:0") is the default, but you can
- explicitly disable subsampling as follows:
-
- cinfo->comp_info[0].v_samp_factor = 1;
- cinfo->comp_info[0].h_samp_factor = 1;
-
-JHUFF_TBL * dc_huff_tbl_ptrs[NUM_HUFF_TBLS]
-JHUFF_TBL * ac_huff_tbl_ptrs[NUM_HUFF_TBLS]
- Pointers to Huffman coding tables, one per table slot, or NULL if
- no table is defined for a slot. Slots 0 and 1 are filled with the
- JPEG sample tables by jpeg_set_defaults(). If you need to allocate
- more table structures, jpeg_alloc_huff_table() may be used.
- Note that optimal Huffman tables can be computed for an image
- by setting optimize_coding, as discussed above; there's seldom
- any need to mess with providing your own Huffman tables.
+ [libjpeg v7+ API/ABI emulation only]
+ Linear quantization scaling factors (0-100, default 100)
+ for use with jpeg_default_qtables().
+ See rdswitch.c and cjpeg.c for an example of usage.
+ Note that the q_scale_factor[] values use "linear" scales, so JPEG
+ quality levels chosen by the user must be converted to these scales
+ using jpeg_quality_scaling(). Here is an example that corresponds to
+ cjpeg -quality 90,70:
+
+ jpeg_set_defaults(cinfo);
+
+ /* Set luminance quality 90. */
+ cinfo->q_scale_factor[0] = jpeg_quality_scaling(90);
+ /* Set chrominance quality 70. */
+ cinfo->q_scale_factor[1] = jpeg_quality_scaling(70);
+
+ jpeg_default_qtables(cinfo, force_baseline);
+
+ CAUTION: Setting separate quality levels for chrominance and luminance
+ is mainly only useful if chrominance subsampling is disabled. 2x2
+ chrominance subsampling (AKA "4:2:0") is the default, but you can
+ explicitly disable subsampling as follows:
+
+ cinfo->comp_info[0].v_samp_factor = 1;
+ cinfo->comp_info[0].h_samp_factor = 1;
+
+JHUFF_TBL *dc_huff_tbl_ptrs[NUM_HUFF_TBLS]
+JHUFF_TBL *ac_huff_tbl_ptrs[NUM_HUFF_TBLS]
+ Pointers to Huffman coding tables, one per table slot, or NULL if
+ no table is defined for a slot. Slots 0 and 1 are filled with the
+ JPEG sample tables by jpeg_set_defaults(). If you need to allocate
+ more table structures, jpeg_alloc_huff_table() may be used.
+ Note that optimal Huffman tables can be computed for an image
+ by setting optimize_coding, as discussed above; there's seldom
+ any need to mess with providing your own Huffman tables.
[libjpeg v7+ API/ABI emulation only]
from the current parameter settings. This can be useful if you are trying
to pick a scaling ratio that will get close to a desired target size.
-JDIMENSION jpeg_width Actual dimensions of output image.
+JDIMENSION jpeg_width Actual dimensions of output image.
JDIMENSION jpeg_height
to use that routine, it's up to you to allocate the array.
int component_id
- The one-byte identifier code to be recorded in the JPEG file for
- this component. For the standard color spaces, we recommend you
- leave the default values alone.
+ The one-byte identifier code to be recorded in the JPEG file for
+ this component. For the standard color spaces, we recommend you
+ leave the default values alone.
int h_samp_factor
int v_samp_factor
- Horizontal and vertical sampling factors for the component; must
- be 1..4 according to the JPEG standard. Note that larger sampling
- factors indicate a higher-resolution component; many people find
- this behavior quite unintuitive. The default values are 2,2 for
- luminance components and 1,1 for chrominance components, except
- for grayscale where 1,1 is used.
+ Horizontal and vertical sampling factors for the component; must
+ be 1..4 according to the JPEG standard. Note that larger sampling
+ factors indicate a higher-resolution component; many people find
+ this behavior quite unintuitive. The default values are 2,2 for
+ luminance components and 1,1 for chrominance components, except
+ for grayscale where 1,1 is used.
int quant_tbl_no
- Quantization table number for component. The default value is
- 0 for luminance components and 1 for chrominance components.
+ Quantization table number for component. The default value is
+ 0 for luminance components and 1 for chrominance components.
int dc_tbl_no
int ac_tbl_no
- DC and AC entropy coding table numbers. The default values are
- 0 for luminance components and 1 for chrominance components.
+ DC and AC entropy coding table numbers. The default values are
+ 0 for luminance components and 1 for chrominance components.
int component_index
- Must equal the component's index in comp_info[]. (Beginning in
- release v6, the compressor library will fill this in automatically;
- you don't have to.)
+ Must equal the component's index in comp_info[]. (Beginning in
+ release v6, the compressor library will fill this in automatically;
+ you don't have to.)
Decompression parameter selection
The following fields in the JPEG object are set by jpeg_read_header() and
may be useful to the application in choosing decompression parameters:
-JDIMENSION image_width Width and height of image
+JDIMENSION image_width Width and height of image
JDIMENSION image_height
-int num_components Number of color components
-J_COLOR_SPACE jpeg_color_space Colorspace of image
-boolean saw_JFIF_marker TRUE if a JFIF APP0 marker was seen
- UINT8 JFIF_major_version Version information from JFIF marker
+int num_components Number of color components
+J_COLOR_SPACE jpeg_color_space Colorspace of image
+boolean saw_JFIF_marker TRUE if a JFIF APP0 marker was seen
+ UINT8 JFIF_major_version Version information from JFIF marker
UINT8 JFIF_minor_version
- UINT8 density_unit Resolution data from JFIF marker
+ UINT8 density_unit Resolution data from JFIF marker
UINT16 X_density
UINT16 Y_density
-boolean saw_Adobe_marker TRUE if an Adobe APP14 marker was seen
- UINT8 Adobe_transform Color transform code from Adobe marker
+boolean saw_Adobe_marker TRUE if an Adobe APP14 marker was seen
+ UINT8 Adobe_transform Color transform code from Adobe marker
The JPEG color space, unfortunately, is something of a guess since the JPEG
standard proper does not provide a way to record it. In practice most files
returned image are:
J_COLOR_SPACE out_color_space
- Output color space. jpeg_read_header() sets an appropriate default
- based on jpeg_color_space; typically it will be RGB or grayscale.
- The application can change this field to request output in a different
- colorspace. For example, set it to JCS_GRAYSCALE to get grayscale
- output from a color file. (This is useful for previewing: grayscale
- output is faster than full color since the color components need not
- be processed.) Note that not all possible color space transforms are
- currently implemented; you may need to extend jdcolor.c if you want an
- unusual conversion.
+ Output color space. jpeg_read_header() sets an appropriate default
+ based on jpeg_color_space; typically it will be RGB or grayscale.
+ The application can change this field to request output in a different
+ colorspace. For example, set it to JCS_GRAYSCALE to get grayscale
+ output from a color file. (This is useful for previewing: grayscale
+ output is faster than full color since the color components need not
+ be processed.) Note that not all possible color space transforms are
+ currently implemented; you may need to extend jdcolor.c if you want an
+ unusual conversion.
unsigned int scale_num, scale_denom
- Scale the image by the fraction scale_num/scale_denom. Default is
- 1/1, or no scaling. Currently, the only supported scaling ratios
- are M/8 with all M from 1 to 16, or any reduced fraction thereof (such
- as 1/2, 3/4, etc.) (The library design allows for arbitrary
- scaling ratios but this is not likely to be implemented any time soon.)
- Smaller scaling ratios permit significantly faster decoding since
- fewer pixels need be processed and a simpler IDCT method can be used.
+ Scale the image by the fraction scale_num/scale_denom. Default is
+ 1/1, or no scaling. Currently, the only supported scaling ratios
+ are M/8 with all M from 1 to 16, or any reduced fraction thereof (such
+ as 1/2, 3/4, etc.) (The library design allows for arbitrary
+ scaling ratios but this is not likely to be implemented any time soon.)
+ Smaller scaling ratios permit significantly faster decoding since
+ fewer pixels need be processed and a simpler IDCT method can be used.
boolean quantize_colors
- If set TRUE, colormapped output will be delivered. Default is FALSE,
- meaning that full-color output will be delivered.
+ If set TRUE, colormapped output will be delivered. Default is FALSE,
+ meaning that full-color output will be delivered.
The next three parameters are relevant only if quantize_colors is TRUE.
int desired_number_of_colors
- Maximum number of colors to use in generating a library-supplied color
- map (the actual number of colors is returned in a different field).
- Default 256. Ignored when the application supplies its own color map.
+ Maximum number of colors to use in generating a library-supplied color
+ map (the actual number of colors is returned in a different field).
+ Default 256. Ignored when the application supplies its own color map.
boolean two_pass_quantize
- If TRUE, an extra pass over the image is made to select a custom color
- map for the image. This usually looks a lot better than the one-size-
- fits-all colormap that is used otherwise. Default is TRUE. Ignored
- when the application supplies its own color map.
+ If TRUE, an extra pass over the image is made to select a custom color
+ map for the image. This usually looks a lot better than the one-size-
+ fits-all colormap that is used otherwise. Default is TRUE. Ignored
+ when the application supplies its own color map.
J_DITHER_MODE dither_mode
- Selects color dithering method. Supported values are:
- JDITHER_NONE no dithering: fast, very low quality
- JDITHER_ORDERED ordered dither: moderate speed and quality
- JDITHER_FS Floyd-Steinberg dither: slow, high quality
- Default is JDITHER_FS. (At present, ordered dither is implemented
- only in the single-pass, standard-colormap case. If you ask for
- ordered dither when two_pass_quantize is TRUE or when you supply
- an external color map, you'll get F-S dithering.)
+ Selects color dithering method. Supported values are:
+ JDITHER_NONE no dithering: fast, very low quality
+ JDITHER_ORDERED ordered dither: moderate speed and quality
+ JDITHER_FS Floyd-Steinberg dither: slow, high quality
+ Default is JDITHER_FS. (At present, ordered dither is implemented
+ only in the single-pass, standard-colormap case. If you ask for
+ ordered dither when two_pass_quantize is TRUE or when you supply
+ an external color map, you'll get F-S dithering.)
When quantize_colors is TRUE, the target color map is described by the next
two fields. colormap is set to NULL by jpeg_read_header(). The application
only accepted for 3-component output color spaces.]
JSAMPARRAY colormap
- The color map, represented as a 2-D pixel array of out_color_components
- rows and actual_number_of_colors columns. Ignored if not quantizing.
- CAUTION: if the JPEG library creates its own colormap, the storage
- pointed to by this field is released by jpeg_finish_decompress().
- Copy the colormap somewhere else first, if you want to save it.
+ The color map, represented as a 2-D pixel array of out_color_components
+ rows and actual_number_of_colors columns. Ignored if not quantizing.
+ CAUTION: if the JPEG library creates its own colormap, the storage
+ pointed to by this field is released by jpeg_finish_decompress().
+ Copy the colormap somewhere else first, if you want to save it.
int actual_number_of_colors
- The number of colors in the color map.
+ The number of colors in the color map.
Additional decompression parameters that the application may set include:
J_DCT_METHOD dct_method
- Selects the algorithm used for the DCT step. Choices are the same
- as described above for compression.
+ Selects the algorithm used for the DCT step. Choices are:
+ JDCT_ISLOW: accurate integer method
+ JDCT_IFAST: less accurate integer method [legacy feature]
+ JDCT_FLOAT: floating-point method [legacy feature]
+ JDCT_DEFAULT: default method (normally JDCT_ISLOW)
+ JDCT_FASTEST: fastest method (normally JDCT_IFAST)
+ When the Independent JPEG Group's software was first released in 1991,
+ the decompression time for a 1-megapixel JPEG image on a mainstream PC
+ was measured in minutes. Thus, JDCT_IFAST provided noticeable
+ performance benefits. On modern CPUs running libjpeg-turbo, however,
+ the decompression time for a 1-megapixel JPEG image is measured in
+ milliseconds, and thus the performance benefits of JDCT_IFAST are much
+ less noticeable. On modern x86/x86-64 CPUs that support AVX2
+ instructions, JDCT_IFAST and JDCT_ISLOW have similar performance. On
+ other types of CPUs, JDCT_IFAST is generally about 5-15% faster than
+ JDCT_ISLOW.
+
+ If the JPEG image was compressed using a quality level of 85 or below,
+ then there should be little or no perceptible quality difference
+ between the two algorithms. When decompressing images that were
+ compressed using quality levels above 85, however, the difference
+ between JDCT_IFAST and JDCT_ISLOW becomes more pronounced. With images
+ compressed using quality=97, for instance, JDCT_IFAST incurs generally
+ about a 4-6 dB loss in PSNR relative to JDCT_ISLOW, but this can be
+ larger for some images. If you can avoid it, do not use JDCT_IFAST
+ when decompressing images that were compressed using quality levels
+ above 97. The algorithm often degenerates for such images and can
+ actually produce a more lossy output image than if the JPEG image had
+ been compressed using lower quality levels.
+
+ JDCT_FLOAT does not produce significantly more accurate results than
+ JDCT_ISLOW, and it is much slower. JDCT_FLOAT may also give different
+ results on different machines due to varying roundoff behavior, whereas
+ the integer methods should give the same results on all machines.
boolean do_fancy_upsampling
- If TRUE, do careful upsampling of chroma components. If FALSE,
- a faster but sloppier method is used. Default is TRUE. The visual
- impact of the sloppier method is often very small.
+ If TRUE, do careful upsampling of chroma components. If FALSE,
+ a faster but sloppier method is used. Default is TRUE. The visual
+ impact of the sloppier method is often very small.
boolean do_block_smoothing
- If TRUE, interblock smoothing is applied in early stages of decoding
- progressive JPEG files; if FALSE, not. Default is TRUE. Early
- progression stages look "fuzzy" with smoothing, "blocky" without.
- In any case, block smoothing ceases to be applied after the first few
- AC coefficients are known to full accuracy, so it is relevant only
- when using buffered-image mode for progressive images.
+ If TRUE, interblock smoothing is applied in early stages of decoding
+ progressive JPEG files; if FALSE, not. Default is TRUE. Early
+ progression stages look "fuzzy" with smoothing, "blocky" without.
+ In any case, block smoothing ceases to be applied after the first few
+ AC coefficients are known to full accuracy, so it is relevant only
+ when using buffered-image mode for progressive images.
boolean enable_1pass_quant
boolean enable_external_quant
boolean enable_2pass_quant
- These are significant only in buffered-image mode, which is
- described in its own section below.
+ These are significant only in buffered-image mode, which is
+ described in its own section below.
The output image dimensions are given by the following fields. These are
JPEG library's memory manager to allocate output buffer space, because you
are supposed to request such buffers *before* jpeg_start_decompress().
-JDIMENSION output_width Actual dimensions of output image.
+JDIMENSION output_width Actual dimensions of output image.
JDIMENSION output_height
-int out_color_components Number of color components in out_color_space.
-int output_components Number of color components returned.
-int rec_outbuf_height Recommended height of scanline buffer.
+int out_color_components Number of color components in out_color_space.
+int output_components Number of color components returned.
+int rec_outbuf_height Recommended height of scanline buffer.
When quantizing colors, output_components is 1, indicating a single color map
index per pixel. Otherwise it equals out_color_components. The output arrays
space depending on in_color_space, but you can override this by calling
jpeg_set_colorspace(). Of course you must select a supported transformation.
jccolor.c currently supports the following transformations:
- RGB => YCbCr
- RGB => GRAYSCALE
- YCbCr => GRAYSCALE
- CMYK => YCCK
+ RGB => YCbCr
+ RGB => GRAYSCALE
+ YCbCr => GRAYSCALE
+ CMYK => YCCK
plus the null transforms: GRAYSCALE => GRAYSCALE, RGB => RGB,
YCbCr => YCbCr, CMYK => CMYK, YCCK => YCCK, and UNKNOWN => UNKNOWN.
selects a default output color space based on (its guess of) jpeg_color_space;
set out_color_space to override this. Again, you must select a supported
transformation. jdcolor.c currently supports
- YCbCr => RGB
- YCbCr => GRAYSCALE
- RGB => GRAYSCALE
- GRAYSCALE => RGB
- YCCK => CMYK
+ YCbCr => RGB
+ YCbCr => GRAYSCALE
+ RGB => GRAYSCALE
+ GRAYSCALE => RGB
+ YCCK => CMYK
as well as the null transforms. (Since GRAYSCALE=>RGB is provided, an
application can force grayscale JPEGs to look like color JPEGs if it only
wants to handle one case.)
routines will cause a message to be printed on stderr, followed by exit().
You can supply your own error handling routines to override this behavior
and to control the treatment of nonfatal warnings and trace/debug messages.
-The file example.c illustrates the most common case, which is to have the
+The file example.txt illustrates the most common case, which is to have the
application regain control after an error rather than exiting.
The JPEG library never writes any message directly; it always goes through
only replacing some of the routines depending on the behavior you need.
This is accomplished by calling jpeg_std_error() as usual, but then overriding
some of the method pointers in the jpeg_error_mgr struct, as illustrated by
-example.c.
+example.txt.
All of the error handling routines will receive a pointer to the JPEG object
(a j_common_ptr which points to either a jpeg_compress_struct or a
handler. The most convenient way to do this is to embed either the JPEG
object or the jpeg_error_mgr struct in a larger structure that contains
additional fields; then casting the passed pointer provides access to the
-additional fields. Again, see example.c for one way to do it. (Beginning
+additional fields. Again, see example.txt for one way to do it. (Beginning
with IJG version 6b, there is also a void pointer "client_data" in each
JPEG object, which the application can also use to find related data.
The library does not touch client_data at all.)
The individual methods that you might wish to override are:
error_exit (j_common_ptr cinfo)
- Receives control for a fatal error. Information sufficient to
- generate the error message has been stored in cinfo->err; call
- output_message to display it. Control must NOT return to the caller;
- generally this routine will exit() or longjmp() somewhere.
- Typically you would override this routine to get rid of the exit()
- default behavior. Note that if you continue processing, you should
- clean up the JPEG object with jpeg_abort() or jpeg_destroy().
+ Receives control for a fatal error. Information sufficient to
+ generate the error message has been stored in cinfo->err; call
+ output_message to display it. Control must NOT return to the caller;
+ generally this routine will exit() or longjmp() somewhere.
+ Typically you would override this routine to get rid of the exit()
+ default behavior. Note that if you continue processing, you should
+ clean up the JPEG object with jpeg_abort() or jpeg_destroy().
output_message (j_common_ptr cinfo)
- Actual output of any JPEG message. Override this to send messages
- somewhere other than stderr. Note that this method does not know
- how to generate a message, only where to send it.
+ Actual output of any JPEG message. Override this to send messages
+ somewhere other than stderr. Note that this method does not know
+ how to generate a message, only where to send it.
-format_message (j_common_ptr cinfo, char * buffer)
- Constructs a readable error message string based on the error info
- stored in cinfo->err. This method is called by output_message. Few
- applications should need to override this method. One possible
- reason for doing so is to implement dynamic switching of error message
- language.
+format_message (j_common_ptr cinfo, char *buffer)
+ Constructs a readable error message string based on the error info
+ stored in cinfo->err. This method is called by output_message. Few
+ applications should need to override this method. One possible
+ reason for doing so is to implement dynamic switching of error message
+ language.
emit_message (j_common_ptr cinfo, int msg_level)
- Decide whether or not to emit a warning or trace message; if so,
- calls output_message. The main reason for overriding this method
- would be to abort on warnings. msg_level is -1 for warnings,
- 0 and up for trace messages.
+ Decide whether or not to emit a warning or trace message; if so,
+ calls output_message. The main reason for overriding this method
+ would be to abort on warnings. msg_level is -1 for warnings,
+ 0 and up for trace messages.
Only error_exit() and emit_message() are called from the rest of the JPEG
library; the other two are internal to the error handler.
addon messages (the addon messages are defined in cderror.h).
Actual invocation of the error handler is done via macros defined in jerror.h:
- ERREXITn(...) for fatal errors
- WARNMSn(...) for corrupt-data warnings
- TRACEMSn(...) for trace and informational messages.
+ ERREXITn(...) for fatal errors
+ WARNMSn(...) for corrupt-data warnings
+ TRACEMSn(...) for trace and informational messages.
These macros store the message code and any additional parameters into the
error handler struct, then invoke the error_exit() or emit_message() method.
The variants of each macro are for varying numbers of additional parameters.
A data destination manager struct contains a pointer and count defining the
next byte to write in the work buffer and the remaining free space:
- JOCTET * next_output_byte; /* => next byte to write in buffer */
- size_t free_in_buffer; /* # of byte spaces remaining in buffer */
+ JOCTET *next_output_byte; /* => next byte to write in buffer */
+ size_t free_in_buffer; /* # of byte spaces remaining in buffer */
The library increments the pointer and decrements the count until the buffer
is filled. The manager's empty_output_buffer method must reset the pointer
A data destination manager provides three methods:
init_destination (j_compress_ptr cinfo)
- Initialize destination. This is called by jpeg_start_compress()
- before any data is actually written. It must initialize
- next_output_byte and free_in_buffer. free_in_buffer must be
- initialized to a positive value.
+ Initialize destination. This is called by jpeg_start_compress()
+ before any data is actually written. It must initialize
+ next_output_byte and free_in_buffer. free_in_buffer must be
+ initialized to a positive value.
empty_output_buffer (j_compress_ptr cinfo)
- This is called whenever the buffer has filled (free_in_buffer
- reaches zero). In typical applications, it should write out the
- *entire* buffer (use the saved start address and buffer length;
- ignore the current state of next_output_byte and free_in_buffer).
- Then reset the pointer & count to the start of the buffer, and
- return TRUE indicating that the buffer has been dumped.
- free_in_buffer must be set to a positive value when TRUE is
- returned. A FALSE return should only be used when I/O suspension is
- desired (this operating mode is discussed in the next section).
+ This is called whenever the buffer has filled (free_in_buffer
+ reaches zero). In typical applications, it should write out the
+ *entire* buffer (use the saved start address and buffer length;
+ ignore the current state of next_output_byte and free_in_buffer).
+ Then reset the pointer & count to the start of the buffer, and
+ return TRUE indicating that the buffer has been dumped.
+ free_in_buffer must be set to a positive value when TRUE is
+ returned. A FALSE return should only be used when I/O suspension is
+ desired (this operating mode is discussed in the next section).
term_destination (j_compress_ptr cinfo)
- Terminate destination --- called by jpeg_finish_compress() after all
- data has been written. In most applications, this must flush any
- data remaining in the buffer. Use either next_output_byte or
- free_in_buffer to determine how much data is in the buffer.
+ Terminate destination --- called by jpeg_finish_compress() after all
+ data has been written. In most applications, this must flush any
+ data remaining in the buffer. Use either next_output_byte or
+ free_in_buffer to determine how much data is in the buffer.
term_destination() is NOT called by jpeg_abort() or jpeg_destroy(). If you
want the destination manager to be cleaned up during an abort, you must do it
defining the next byte to read from the work buffer and the number of bytes
remaining:
- const JOCTET * next_input_byte; /* => next byte to read from buffer */
- size_t bytes_in_buffer; /* # of bytes remaining in buffer */
+ const JOCTET *next_input_byte; /* => next byte to read from buffer */
+ size_t bytes_in_buffer; /* # of bytes remaining in buffer */
The library increments the pointer and decrements the count until the buffer
is emptied. The manager's fill_input_buffer method must reset the pointer and
A data source manager provides five methods:
init_source (j_decompress_ptr cinfo)
- Initialize source. This is called by jpeg_read_header() before any
- data is actually read. Unlike init_destination(), it may leave
- bytes_in_buffer set to 0 (in which case a fill_input_buffer() call
- will occur immediately).
+ Initialize source. This is called by jpeg_read_header() before any
+ data is actually read. Unlike init_destination(), it may leave
+ bytes_in_buffer set to 0 (in which case a fill_input_buffer() call
+ will occur immediately).
fill_input_buffer (j_decompress_ptr cinfo)
- This is called whenever bytes_in_buffer has reached zero and more
- data is wanted. In typical applications, it should read fresh data
- into the buffer (ignoring the current state of next_input_byte and
- bytes_in_buffer), reset the pointer & count to the start of the
- buffer, and return TRUE indicating that the buffer has been reloaded.
- It is not necessary to fill the buffer entirely, only to obtain at
- least one more byte. bytes_in_buffer MUST be set to a positive value
- if TRUE is returned. A FALSE return should only be used when I/O
- suspension is desired (this mode is discussed in the next section).
+ This is called whenever bytes_in_buffer has reached zero and more
+ data is wanted. In typical applications, it should read fresh data
+ into the buffer (ignoring the current state of next_input_byte and
+ bytes_in_buffer), reset the pointer & count to the start of the
+ buffer, and return TRUE indicating that the buffer has been reloaded.
+ It is not necessary to fill the buffer entirely, only to obtain at
+ least one more byte. bytes_in_buffer MUST be set to a positive value
+ if TRUE is returned. A FALSE return should only be used when I/O
+ suspension is desired (this mode is discussed in the next section).
skip_input_data (j_decompress_ptr cinfo, long num_bytes)
- Skip num_bytes worth of data. The buffer pointer and count should
- be advanced over num_bytes input bytes, refilling the buffer as
- needed. This is used to skip over a potentially large amount of
- uninteresting data (such as an APPn marker). In some applications
- it may be possible to optimize away the reading of the skipped data,
- but it's not clear that being smart is worth much trouble; large
- skips are uncommon. bytes_in_buffer may be zero on return.
- A zero or negative skip count should be treated as a no-op.
+ Skip num_bytes worth of data. The buffer pointer and count should
+ be advanced over num_bytes input bytes, refilling the buffer as
+ needed. This is used to skip over a potentially large amount of
+ uninteresting data (such as an APPn marker). In some applications
+ it may be possible to optimize away the reading of the skipped data,
+ but it's not clear that being smart is worth much trouble; large
+ skips are uncommon. bytes_in_buffer may be zero on return.
+ A zero or negative skip count should be treated as a no-op.
resync_to_restart (j_decompress_ptr cinfo, int desired)
- This routine is called only when the decompressor has failed to find
- a restart (RSTn) marker where one is expected. Its mission is to
- find a suitable point for resuming decompression. For most
- applications, we recommend that you just use the default resync
- procedure, jpeg_resync_to_restart(). However, if you are able to back
- up in the input data stream, or if you have a-priori knowledge about
- the likely location of restart markers, you may be able to do better.
- Read the read_restart_marker() and jpeg_resync_to_restart() routines
- in jdmarker.c if you think you'd like to implement your own resync
- procedure.
+ This routine is called only when the decompressor has failed to find
+ a restart (RSTn) marker where one is expected. Its mission is to
+ find a suitable point for resuming decompression. For most
+ applications, we recommend that you just use the default resync
+ procedure, jpeg_resync_to_restart(). However, if you are able to back
+ up in the input data stream, or if you have a-priori knowledge about
+ the likely location of restart markers, you may be able to do better.
+ Read the read_restart_marker() and jpeg_resync_to_restart() routines
+ in jdmarker.c if you think you'd like to implement your own resync
+ procedure.
term_source (j_decompress_ptr cinfo)
- Terminate source --- called by jpeg_finish_decompress() after all
- data has been read. Often a no-op.
+ Terminate source --- called by jpeg_finish_decompress() after all
+ data has been read. Often a no-op.
For both fill_input_buffer() and skip_input_data(), there is no such thing
as an EOF return. If the end of the file has been reached, the routine has
* jpeg_read_header(): will return JPEG_SUSPENDED.
* jpeg_start_decompress(): will return FALSE, rather than its usual TRUE.
* jpeg_read_scanlines(): will return the number of scanlines already
- completed (possibly 0).
+ completed (possibly 0).
* jpeg_finish_decompress(): will return FALSE, rather than its usual TRUE.
The surrounding application must recognize these cases, load more data into
the input buffer, and repeat the call. In the case of jpeg_read_scanlines(),
The basic control flow for buffered-image decoding is
- jpeg_create_decompress()
- set data source
- jpeg_read_header()
- set overall decompression parameters
- cinfo.buffered_image = TRUE; /* select buffered-image mode */
- jpeg_start_decompress()
- for (each output pass) {
- adjust output decompression parameters if required
- jpeg_start_output() /* start a new output pass */
- for (all scanlines in image) {
- jpeg_read_scanlines()
- display scanlines
- }
- jpeg_finish_output() /* terminate output pass */
- }
- jpeg_finish_decompress()
- jpeg_destroy_decompress()
+ jpeg_create_decompress()
+ set data source
+ jpeg_read_header()
+ set overall decompression parameters
+ cinfo.buffered_image = TRUE; /* select buffered-image mode */
+ jpeg_start_decompress()
+ for (each output pass) {
+ adjust output decompression parameters if required
+ jpeg_start_output() /* start a new output pass */
+ for (all scanlines in image) {
+ jpeg_read_scanlines()
+ display scanlines
+ }
+ jpeg_finish_output() /* terminate output pass */
+ }
+ jpeg_finish_decompress()
+ jpeg_destroy_decompress()
This differs from ordinary unbuffered decoding in that there is an additional
level of looping. The application can choose how many output passes to make
The simplest approach to displaying progressive images is to do one display
pass for each scan appearing in the input file. In this case the outer loop
condition is typically
- while (! jpeg_input_complete(&cinfo))
+ while (!jpeg_input_complete(&cinfo))
and the start-output call should read
- jpeg_start_output(&cinfo, cinfo.input_scan_number);
+ jpeg_start_output(&cinfo, cinfo.input_scan_number);
The second parameter to jpeg_start_output() indicates which scan of the input
file is to be displayed; the scans are numbered starting at 1 for this
purpose. (You can use a loop counter starting at 1 if you like, but using
cause the library to decode input data in advance of what's needed to produce
output. This is done by calling the routine jpeg_consume_input().
The return value is one of the following:
- JPEG_REACHED_SOS: reached an SOS marker (the start of a new scan)
- JPEG_REACHED_EOI: reached the EOI marker (end of image)
- JPEG_ROW_COMPLETED: completed reading one MCU row of compressed data
- JPEG_SCAN_COMPLETED: completed reading last MCU row of current scan
- JPEG_SUSPENDED: suspended before completing any of the above
+ JPEG_REACHED_SOS: reached an SOS marker (the start of a new scan)
+ JPEG_REACHED_EOI: reached the EOI marker (end of image)
+ JPEG_ROW_COMPLETED: completed reading one MCU row of compressed data
+ JPEG_SCAN_COMPLETED: completed reading last MCU row of current scan
+ JPEG_SUSPENDED: suspended before completing any of the above
(JPEG_SUSPENDED can occur only if a suspending data source is used.) This
routine can be called at any time after initializing the JPEG object. It
reads some additional data and returns when one of the indicated significant
output pass after receiving all the data; otherwise your last display may not
be full quality across the whole screen. So the right outer loop logic is
something like this:
- do {
- absorb any waiting input by calling jpeg_consume_input()
- final_pass = jpeg_input_complete(&cinfo);
- adjust output decompression parameters if required
- jpeg_start_output(&cinfo, cinfo.input_scan_number);
- ...
- jpeg_finish_output()
- } while (! final_pass);
+ do {
+ absorb any waiting input by calling jpeg_consume_input()
+ final_pass = jpeg_input_complete(&cinfo);
+ adjust output decompression parameters if required
+ jpeg_start_output(&cinfo, cinfo.input_scan_number);
+ ...
+ jpeg_finish_output()
+ } while (!final_pass);
rather than quitting as soon as jpeg_input_complete() returns TRUE. This
arrangement makes it simple to use higher-quality decoding parameters
for the final pass. But if you don't want to use special parameters for
the final pass, the right loop logic is like this:
- for (;;) {
- absorb any waiting input by calling jpeg_consume_input()
- jpeg_start_output(&cinfo, cinfo.input_scan_number);
- ...
- jpeg_finish_output()
- if (jpeg_input_complete(&cinfo) &&
- cinfo.input_scan_number == cinfo.output_scan_number)
- break;
- }
+ for (;;) {
+ absorb any waiting input by calling jpeg_consume_input()
+ jpeg_start_output(&cinfo, cinfo.input_scan_number);
+ ...
+ jpeg_finish_output()
+ if (jpeg_input_complete(&cinfo) &&
+ cinfo.input_scan_number == cinfo.output_scan_number)
+ break;
+ }
In this case you don't need to know in advance whether an output pass is to
be the last one, so it's not necessary to have reached EOF before starting
the final output pass; rather, what you want to test is whether the output
one(s) you intend to use before you call jpeg_start_decompress(). (If we did
not require this, the max_memory_to_use setting would be a complete fiction.)
You do this by setting one or more of these three cinfo fields to TRUE:
- enable_1pass_quant Fixed color cube colormap
- enable_external_quant Externally-supplied colormap
- enable_2pass_quant Two-pass custom colormap
+ enable_1pass_quant Fixed color cube colormap
+ enable_external_quant Externally-supplied colormap
+ enable_2pass_quant Two-pass custom colormap
All three are initialized FALSE by jpeg_read_header(). But
jpeg_start_decompress() automatically sets TRUE the one selected by the
current two_pass_quantize and colormap settings, so you only need to set the
A sure-fire way to create matching tables-only and abbreviated image files
is to proceed as follows:
- create JPEG compression object
- set JPEG parameters
- set destination to tables-only file
- jpeg_write_tables(&cinfo);
- set destination to image file
- jpeg_start_compress(&cinfo, FALSE);
- write data...
- jpeg_finish_compress(&cinfo);
+ create JPEG compression object
+ set JPEG parameters
+ set destination to tables-only file
+ jpeg_write_tables(&cinfo);
+ set destination to image file
+ jpeg_start_compress(&cinfo, FALSE);
+ write data...
+ jpeg_finish_compress(&cinfo);
Since the JPEG parameters are not altered between writing the table file and
the abbreviated image file, the same tables are sure to be used. Of course,
if (cinfo.quant_tbl_ptrs[n] == NULL)
cinfo.quant_tbl_ptrs[n] = jpeg_alloc_quant_table((j_common_ptr) &cinfo);
- quant_ptr = cinfo.quant_tbl_ptrs[n]; /* quant_ptr is JQUANT_TBL* */
+ quant_ptr = cinfo.quant_tbl_ptrs[n]; /* quant_ptr is JQUANT_TBL* */
for (i = 0; i < 64; i++) {
/* Qtable[] is desired quantization table, in natural array order */
quant_ptr->quantval[i] = Qtable[i];
if (cinfo.ac_huff_tbl_ptrs[n] == NULL)
cinfo.ac_huff_tbl_ptrs[n] = jpeg_alloc_huff_table((j_common_ptr) &cinfo);
- huff_ptr = cinfo.ac_huff_tbl_ptrs[n]; /* huff_ptr is JHUFF_TBL* */
+ huff_ptr = cinfo.ac_huff_tbl_ptrs[n]; /* huff_ptr is JHUFF_TBL* */
for (i = 1; i <= 16; i++) {
/* counts[i] is number of Huffman codes of length i bits, i=1..16 */
huff_ptr->bits[i] = counts[i];
FALSE to indicate that you do not require an image to be present. Thus, the
typical scenario is
- create JPEG decompression object
- set source to tables-only file
- jpeg_read_header(&cinfo, FALSE);
- set source to abbreviated image file
- jpeg_read_header(&cinfo, TRUE);
- set decompression parameters
- jpeg_start_decompress(&cinfo);
- read data...
- jpeg_finish_decompress(&cinfo);
+ create JPEG decompression object
+ set source to tables-only file
+ jpeg_read_header(&cinfo, FALSE);
+ set source to abbreviated image file
+ jpeg_read_header(&cinfo, TRUE);
+ set decompression parameters
+ jpeg_start_decompress(&cinfo);
+ read data...
+ jpeg_finish_decompress(&cinfo);
In some cases, you may want to read a file without knowing whether it contains
an image or just tables. In that case, pass FALSE and check the return value
"JPEG_APP0 + n" for APPn. (Actually, jpeg_write_marker will let you write
any marker type, but we don't recommend writing any other kinds of marker.)
For example, to write a user comment string pointed to by comment_text:
- jpeg_write_marker(cinfo, JPEG_COM, comment_text, strlen(comment_text));
+ jpeg_write_marker(cinfo, JPEG_COM, comment_text, strlen(comment_text));
If it's not convenient to store all the marker data in memory at once,
you can instead call jpeg_write_m_header() followed by multiple calls to
To save the contents of special markers in memory, call
- jpeg_save_markers(cinfo, marker_code, length_limit)
+ jpeg_save_markers(cinfo, marker_code, length_limit)
where marker_code is the marker type to save, JPEG_COM or JPEG_APP0+n.
(To arrange to save all the special marker types, you need to call this
routine 17 times, for COM and APP0-APP15.) If the incoming marker is longer
If you want to supply your own marker-reading routine, you do it by calling
jpeg_set_marker_processor(). A marker processor routine must have the
signature
- boolean jpeg_marker_parser_method (j_decompress_ptr cinfo)
+ boolean jpeg_marker_parser_method (j_decompress_ptr cinfo)
Although the marker code is not explicitly passed, the routine can find it
in cinfo->unread_marker. At the time of call, the marker proper has been
read from the data source module. The processor routine is responsible for
Also, see jpegtran.c for an example of using jpeg_save_markers.
+ICC profiles
+------------
+
+Two functions are provided for writing and reading International Color
+Consortium (ICC) device profiles embedded in JFIF JPEG image files:
+
+ void jpeg_write_icc_profile (j_compress_ptr cinfo,
+ const JOCTET *icc_data_ptr,
+ unsigned int icc_data_len);
+ boolean jpeg_read_icc_profile (j_decompress_ptr cinfo,
+ JOCTET **icc_data_ptr,
+ unsigned int *icc_data_len);
+
+The ICC has defined a standard for including such data in JPEG "APP2" markers.
+The aforementioned functions do not know anything about the internal structure
+of the ICC profile data; they just know how to embed the profile data into a
+JPEG file while writing it, or to extract the profile data from a JPEG file
+while reading it.
+
+jpeg_write_icc_profile() must be called after calling jpeg_start_compress() and
+before the first call to jpeg_write_scanlines() or jpeg_write_raw_data(). This
+ordering ensures that the APP2 marker(s) will appear after the SOI and JFIF or
+Adobe markers, but before all other data.
+
+jpeg_read_icc_profile() returns TRUE if an ICC profile was found and FALSE
+otherwise. If an ICC profile was found, then the function will allocate a
+memory region containing the profile and will return a pointer to that memory
+region in *icc_data_ptr, as well as the length of the region in *icc_data_len.
+This memory region is allocated by the library using malloc() and must be freed
+by the caller using free() when the memory region is no longer needed. Callers
+wishing to use jpeg_read_icc_profile() must call
+
+ jpeg_save_markers(cinfo, JPEG_APP0 + 2, 0xFFFF);
+
+prior to calling jpeg_read_header(). jpeg_read_icc_profile() can be called at
+any point between jpeg_read_header() and jpeg_finish_decompress().
+
+
Raw (downsampled) image data
----------------------------
The required dimensions of the supplied data can be computed for each
component as
- cinfo->comp_info[i].width_in_blocks*DCTSIZE samples per row
- cinfo->comp_info[i].height_in_blocks*DCTSIZE rows in image
+ cinfo->comp_info[i].width_in_blocks*DCTSIZE samples per row
+ cinfo->comp_info[i].height_in_blocks*DCTSIZE rows in image
after jpeg_start_compress() has initialized those fields. If the valid data
is smaller than this, it must be padded appropriately. For some sampling
factors and image sizes, additional dummy DCT blocks are inserted to make
blocks itself; it does not read them from your supplied data. Therefore you
need never pad by more than DCTSIZE samples. An example may help here.
Assume 2h2v downsampling of YCbCr data, that is
- cinfo->comp_info[0].h_samp_factor = 2 for Y
- cinfo->comp_info[0].v_samp_factor = 2
- cinfo->comp_info[1].h_samp_factor = 1 for Cb
- cinfo->comp_info[1].v_samp_factor = 1
- cinfo->comp_info[2].h_samp_factor = 1 for Cr
- cinfo->comp_info[2].v_samp_factor = 1
+ cinfo->comp_info[0].h_samp_factor = 2 for Y
+ cinfo->comp_info[0].v_samp_factor = 2
+ cinfo->comp_info[1].h_samp_factor = 1 for Cb
+ cinfo->comp_info[1].v_samp_factor = 1
+ cinfo->comp_info[2].h_samp_factor = 1 for Cr
+ cinfo->comp_info[2].v_samp_factor = 1
and suppose that the nominal image dimensions (cinfo->image_width and
cinfo->image_height) are 101x101 pixels. Then jpeg_start_compress() will
compute downsampled_width = 101 and width_in_blocks = 13 for Y,
can use the same callback routine for both compression and decompression.
The jpeg_progress_mgr struct contains four fields which are set by the library:
- long pass_counter; /* work units completed in this pass */
- long pass_limit; /* total number of work units in this pass */
- int completed_passes; /* passes completed so far */
- int total_passes; /* total number of passes expected */
+ long pass_counter; /* work units completed in this pass */
+ long pass_limit; /* total number of work units in this pass */
+ int completed_passes; /* passes completed so far */
+ int total_passes; /* total number of passes expected */
During any one pass, pass_counter increases from 0 up to (not including)
pass_limit; the step size is usually but not necessarily 1. The pass_limit
value may change from one pass to another. The expected total number of
passes is in total_passes, and the number of passes already completed is in
completed_passes. Thus the fraction of work completed may be estimated as
- completed_passes + (pass_counter/pass_limit)
- --------------------------------------------
- total_passes
+ completed_passes + (pass_counter/pass_limit)
+ --------------------------------------------
+ total_passes
ignoring the fact that the passes may not be equal amounts of work.
When decompressing, pass_limit can even change within a pass, because it
jpeg_finish_compress, jpeg_finish_decompress, or jpeg_abort. You can call the
memory manager yourself to allocate structures that will automatically be
freed at these times. Typical code for this is
- ptr = (*cinfo->mem->alloc_small) ((j_common_ptr) cinfo, JPOOL_IMAGE, size);
+ ptr = (*cinfo->mem->alloc_small) ((j_common_ptr)cinfo, JPOOL_IMAGE, size);
Use JPOOL_PERMANENT to get storage that lasts as long as the JPEG object.
Use alloc_large instead of alloc_small for anything bigger than a few Kbytes.
There are also alloc_sarray and alloc_barray routines that automatically
buffers. Such buffers are treated as "virtual arrays": only the current strip
need be in memory, and the rest can be swapped out to a temporary file.
-If you use the simplest memory manager back end (jmemnobs.c), then no
-temporary files are used; virtual arrays are simply malloc()'d. Images bigger
-than memory can be processed only if your system supports virtual memory.
-The other memory manager back ends support temporary files of various flavors
-and thus work in machines without virtual memory. They may also be useful on
-Unix machines if you need to process images that exceed available swap space.
-
When using temporary files, the library will make the in-memory buffers for
its virtual arrays just big enough to stay within a "maximum memory" setting.
Your application can set this limit by setting cinfo->mem->max_memory_to_use
it's too small to be worth worrying about; so a reasonable safety margin
should be left when setting max_memory_to_use.
-If you use the jmemname.c or jmemdos.c memory manager back end, it is
-important to clean up the JPEG object properly to ensure that the temporary
-files get deleted. (This is especially crucial with jmemdos.c, where the
-"temporary files" may be extended-memory segments; if they are not freed,
-DOS will require a reboot to recover the memory.) Thus, with these memory
-managers, it's a good idea to provide a signal handler that will trap any
-early exit from your program. The handler should call either jpeg_abort()
-or jpeg_destroy() for any active JPEG objects. A handler is not needed with
-jmemnobs.c, and shouldn't be necessary with jmemansi.c or jmemmac.c either,
-since the C library is supposed to take care of deleting files made with
-tmpfile().
+NOTE: Unless you develop your own memory manager back end, then temporary files
+will never be used. The back end provided in libjpeg-turbo (jmemnobs.c) simply
+malloc()s and free()s virtual arrays, and an error occurs if the required
+memory exceeds the limit specified in cinfo->mem->max_memory_to_use.
Memory usage
larger than a char, so it affects the surrounding application's image data.
The sample applications cjpeg and djpeg can support 12-bit mode only for PPM
and GIF file formats; you must disable the other file formats to compile a
-12-bit cjpeg or djpeg. (install.txt has more information about that.)
-At present, a 12-bit library can handle *only* 12-bit images, not both
-precisions. (If you need to include both 8- and 12-bit libraries in a single
-application, you could probably do it by defining NEED_SHORT_EXTERNAL_NAMES
-for just one of the copies. You'd have to access the 8-bit and 12-bit copies
-from separate application source files. This is untested ... if you try it,
-we'd like to hear whether it works!)
+12-bit cjpeg or djpeg. At present, a 12-bit library can handle *only* 12-bit
+images, not both precisions.
Note that a 12-bit library always compresses in Huffman optimization mode,
in order to generate valid Huffman tables. This is necessary because our
You can also save a few K by not having text error messages in the library;
the standard error message table occupies about 5Kb. This is particularly
-reasonable for embedded applications where there's no good way to display
+reasonable for embedded applications where there's no good way to display
a message anyway. To do this, remove the creation of the message table
(jpeg_std_message_table[]) from jerror.c, and alter format_message to do
something reasonable without it. You could output the numeric value of the
library to be less portable than is claimed here, we'd appreciate hearing
about them.)
-The code works fine on ANSI C, C++, and pre-ANSI C compilers, using any of
-the popular system include file setups, and some not-so-popular ones too.
-See install.txt for configuration procedures.
+The code works fine on ANSI C and C++ compilers, using any of the popular
+system include file setups, and some not-so-popular ones too.
The code is not dependent on the exact sizes of the C data types. As
distributed, we make the assumptions that
- char is at least 8 bits wide
- short is at least 16 bits wide
- int is at least 16 bits wide
- long is at least 32 bits wide
+ char is at least 8 bits wide
+ short is at least 16 bits wide
+ int is at least 16 bits wide
+ long is at least 32 bits wide
(These are the minimum requirements of the ANSI C standard.) Wider types will
work fine, although memory may be used inefficiently if char is much larger
than 8 bits or short is much bigger than 16 bits. The code should work
manager "back end" module, so you can use a different memory allocator by
replacing that one file.
-The code generally assumes that C names must be unique in the first 15
-characters. However, global function names can be made unique in the
-first 6 characters by defining NEED_SHORT_EXTERNAL_NAMES.
-
More info about porting the code may be gleaned by reading jconfig.txt,
jmorecfg.h, and jinclude.h.
-
-
-Notes for MS-DOS implementors
------------------------------
-
-The IJG code is designed to work efficiently in 80x86 "small" or "medium"
-memory models (i.e., data pointers are 16 bits unless explicitly declared
-"far"; code pointers can be either size). You may be able to use small
-model to compile cjpeg or djpeg by itself, but you will probably have to use
-medium model for any larger application. This won't make much difference in
-performance. You *will* take a noticeable performance hit if you use a
-large-data memory model (perhaps 10%-25%), and you should avoid "huge" model
-if at all possible.
-
-The JPEG library typically needs 2Kb-3Kb of stack space. It will also
-malloc about 20K-30K of near heap space while executing (and lots of far
-heap, but that doesn't count in this calculation). This figure will vary
-depending on selected operating mode, and to a lesser extent on image size.
-There is also about 5Kb-6Kb of constant data which will be allocated in the
-near data segment (about 4Kb of this is the error message table).
-Thus you have perhaps 20K available for other modules' static data and near
-heap space before you need to go to a larger memory model. The C library's
-static data will account for several K of this, but that still leaves a good
-deal for your needs. (If you are tight on space, you could reduce the sizes
-of the I/O buffers allocated by jdatasrc.c and jdatadst.c, say from 4K to
-1K. Another possibility is to move the error message table to far memory;
-this should be doable with only localized hacking on jerror.c.)
-
-About 2K of the near heap space is "permanent" memory that will not be
-released until you destroy the JPEG object. This is only an issue if you
-save a JPEG object between compression or decompression operations.
-
-Far data space may also be a tight resource when you are dealing with large
-images. The most memory-intensive case is decompression with two-pass color
-quantization, or single-pass quantization to an externally supplied color
-map. This requires a 128Kb color lookup table plus strip buffers amounting
-to about 40 bytes per column for typical sampling ratios (eg, about 25600
-bytes for a 640-pixel-wide image). You may not be able to process wide
-images if you have large data structures of your own.
-
-Of course, all of these concerns vanish if you use a 32-bit flat-memory-model
-compiler, such as DJGPP or Watcom C. We highly recommend flat model if you
-can use it; the JPEG library is significantly faster in flat model.
projects / platform / upstream / libjpeg-turbo.git / blobdiff