Decompression parameter selection is somewhat simpler than compression parameter selection, since all of the JPEG internal parameters are recorded in the source file and need not be supplied by the application. Decompression parameters control the postprocessing done on the image to deliver it in a format suitable for the application's use. Many of the parameters control speed/quality tradeoffs, in which faster decompression may be obtained at the price of a poorer-quality image. The defaults select the highest quality (slowest) processing.
The following properties in the JPEG object are set by jpeg_read_header(Boolean) and may be useful to the application in choosing decompression parameters:
| Property | Description |
|---|---|
| Image_width, Image_height | Width and height of image |
| Num_components | Number of color components |
| Jpeg_color_space | Colorspace of image |
| Density_unit, X_density, Y_density | Resolution data from JFIF marker |
The JPEG color space, unfortunately, is something of a guess since the JPEG standard proper does not provide a way to record it. In practice most files adhere to the JFIF or Adobe conventions, and the decoder will recognize these correctly. See Special color spaces for more info.
The decompression parameters that determine the basic properties of the returned image are:
| Parameter | Description |
|---|---|
| Out_color_space | Output color space |
| Scale_num, Scale_denom | Scale the image by the fraction Scale_num/Scale_denom |
| Quantize_colors | Chooses colormapped or full-color output |
The next three parameters are relevant only if Quantize_colors is true.
| Property | Description |
|---|---|
| Desired_number_of_colors | Maximum number of colors to use in generating a library-supplied color map |
| Two_pass_quantize | If true, an extra pass over the image is made to select a custom color map for the image |
| Dither_mode | Selects color dithering method |
When Quantize_colors is true, the target color map is described by the next two properties. Colormap is set to null by jpeg_read_header(Boolean). The application can supply a color map by setting Colormap non-null and setting Actual_number_of_colors to the map size. Otherwise, jpeg_start_decompress() selects a suitable color map and sets these two properties itself.
| Property | Description |
|---|---|
| Colormap | The color map, represented as a 2-D pixel array of Out_color_components rows and Actual_number_of_colors columns |
| Actual_number_of_colors | The number of colors in the color map |
Additional decompression parameters that the application may set include:
| Parameter | Description |
|---|---|
| Dct_method | Selects the algorithm used for the DCT step |
| Do_fancy_upsampling | Upsampling of chroma components |
| Do_block_smoothing | Apply interblock smoothing in early stages of decoding progressive JPEG files |
| Enable_1pass_quant, Enable_external_quant, Enable_2pass_quant | These are significant only in buffered-image mode |
The output image dimensions are given by the following properties. These are computed from the source image dimensions and the decompression parameters by jpeg_start_decompress(). You can also call jpeg_calc_output_dimensions() to obtain the values that will result from the current parameter settings. This can be useful if you are trying to pick a scaling ratio that will get close to a desired target size.
| Property | Description |
|---|---|
| Output_width, Output_height | Actual dimensions of output image |
| Out_color_components | Number of color components in Out_color_space |
| Output_components | Number of color components returned |
| Rec_outbuf_height | Recommended height of scanline buffer |
The output arrays are required to be Output_width * Output_components bytes wide.