4 * Copyright (C) 1991-1997, Thomas G. Lane.
5 * Modified 2002-2013 by Guido Vollbeding.
6 * This file is part of the Independent JPEG Group's software.
7 * For conditions of distribution and use, see the accompanying README file.
9 * This file contains master control logic for the JPEG decompressor.
10 * These routines are concerned with selecting the modules to be executed
11 * and with determining the number of passes and the work to be done in each
15 #define JPEG_INTERNALS
23 struct jpeg_decomp_master pub
; /* public fields */
25 int pass_number
; /* # of passes completed */
27 boolean using_merged_upsample
; /* TRUE if using merged upsample/cconvert */
29 /* Saved references to initialized quantizer modules,
30 * in case we need to switch modes.
32 struct jpeg_color_quantizer
* quantizer_1pass
;
33 struct jpeg_color_quantizer
* quantizer_2pass
;
36 typedef my_decomp_master
* my_master_ptr
;
40 * Determine whether merged upsample/color conversion should be used.
41 * CRUCIAL: this must match the actual capabilities of jdmerge.c!
45 use_merged_upsample (j_decompress_ptr cinfo
)
47 #ifdef UPSAMPLE_MERGING_SUPPORTED
48 /* Merging is the equivalent of plain box-filter upsampling */
49 if (cinfo
->do_fancy_upsampling
|| cinfo
->CCIR601_sampling
)
51 /* jdmerge.c only supports YCC=>RGB color conversion */
52 if (cinfo
->jpeg_color_space
!= JCS_YCbCr
|| cinfo
->num_components
!= 3 ||
53 cinfo
->out_color_space
!= JCS_RGB
||
54 cinfo
->out_color_components
!= RGB_PIXELSIZE
||
55 cinfo
->color_transform
)
57 /* and it only handles 2h1v or 2h2v sampling ratios */
58 if (cinfo
->comp_info
[0].h_samp_factor
!= 2 ||
59 cinfo
->comp_info
[1].h_samp_factor
!= 1 ||
60 cinfo
->comp_info
[2].h_samp_factor
!= 1 ||
61 cinfo
->comp_info
[0].v_samp_factor
> 2 ||
62 cinfo
->comp_info
[1].v_samp_factor
!= 1 ||
63 cinfo
->comp_info
[2].v_samp_factor
!= 1)
65 /* furthermore, it doesn't work if we've scaled the IDCTs differently */
66 if (cinfo
->comp_info
[0].DCT_h_scaled_size
!= cinfo
->min_DCT_h_scaled_size
||
67 cinfo
->comp_info
[1].DCT_h_scaled_size
!= cinfo
->min_DCT_h_scaled_size
||
68 cinfo
->comp_info
[2].DCT_h_scaled_size
!= cinfo
->min_DCT_h_scaled_size
||
69 cinfo
->comp_info
[0].DCT_v_scaled_size
!= cinfo
->min_DCT_v_scaled_size
||
70 cinfo
->comp_info
[1].DCT_v_scaled_size
!= cinfo
->min_DCT_v_scaled_size
||
71 cinfo
->comp_info
[2].DCT_v_scaled_size
!= cinfo
->min_DCT_v_scaled_size
)
73 /* ??? also need to test for upsample-time rescaling, when & if supported */
74 return TRUE
; /* by golly, it'll work... */
82 * Compute output image dimensions and related values.
83 * NOTE: this is exported for possible use by application.
84 * Hence it mustn't do anything that can't be done twice.
85 * Also note that it may be called before the master module is initialized!
89 jpeg_calc_output_dimensions (j_decompress_ptr cinfo
)
90 /* Do computations that are needed before master selection phase.
91 * This function is used for full decompression.
94 #ifdef IDCT_SCALING_SUPPORTED
96 jpeg_component_info
*compptr
;
99 /* Prevent application from calling me at wrong times */
100 if (cinfo
->global_state
!= DSTATE_READY
)
101 ERREXIT1(cinfo
, JERR_BAD_STATE
, cinfo
->global_state
);
103 /* Compute core output image dimensions and DCT scaling choices. */
104 jpeg_core_output_dimensions(cinfo
);
106 #ifdef IDCT_SCALING_SUPPORTED
108 /* In selecting the actual DCT scaling for each component, we try to
109 * scale up the chroma components via IDCT scaling rather than upsampling.
110 * This saves time if the upsampler gets to use 1:1 scaling.
111 * Note this code adapts subsampling ratios which are powers of 2.
113 for (ci
= 0, compptr
= cinfo
->comp_info
; ci
< cinfo
->num_components
;
116 while (cinfo
->min_DCT_h_scaled_size
* ssize
<=
117 (cinfo
->do_fancy_upsampling
? DCTSIZE
: DCTSIZE
/ 2) &&
118 (cinfo
->max_h_samp_factor
% (compptr
->h_samp_factor
* ssize
* 2)) == 0) {
121 compptr
->DCT_h_scaled_size
= cinfo
->min_DCT_h_scaled_size
* ssize
;
123 while (cinfo
->min_DCT_v_scaled_size
* ssize
<=
124 (cinfo
->do_fancy_upsampling
? DCTSIZE
: DCTSIZE
/ 2) &&
125 (cinfo
->max_v_samp_factor
% (compptr
->v_samp_factor
* ssize
* 2)) == 0) {
128 compptr
->DCT_v_scaled_size
= cinfo
->min_DCT_v_scaled_size
* ssize
;
130 /* We don't support IDCT ratios larger than 2. */
131 if (compptr
->DCT_h_scaled_size
> compptr
->DCT_v_scaled_size
* 2)
132 compptr
->DCT_h_scaled_size
= compptr
->DCT_v_scaled_size
* 2;
133 else if (compptr
->DCT_v_scaled_size
> compptr
->DCT_h_scaled_size
* 2)
134 compptr
->DCT_v_scaled_size
= compptr
->DCT_h_scaled_size
* 2;
137 /* Recompute downsampled dimensions of components;
138 * application needs to know these if using raw downsampled data.
140 for (ci
= 0, compptr
= cinfo
->comp_info
; ci
< cinfo
->num_components
;
142 /* Size in samples, after IDCT scaling */
143 compptr
->downsampled_width
= (JDIMENSION
)
144 jdiv_round_up((long) cinfo
->image_width
*
145 (long) (compptr
->h_samp_factor
* compptr
->DCT_h_scaled_size
),
146 (long) (cinfo
->max_h_samp_factor
* cinfo
->block_size
));
147 compptr
->downsampled_height
= (JDIMENSION
)
148 jdiv_round_up((long) cinfo
->image_height
*
149 (long) (compptr
->v_samp_factor
* compptr
->DCT_v_scaled_size
),
150 (long) (cinfo
->max_v_samp_factor
* cinfo
->block_size
));
153 #endif /* IDCT_SCALING_SUPPORTED */
155 /* Report number of components in selected colorspace. */
156 /* Probably this should be in the color conversion module... */
157 switch (cinfo
->out_color_space
) {
159 cinfo
->out_color_components
= 1;
163 cinfo
->out_color_components
= RGB_PIXELSIZE
;
167 cinfo
->out_color_components
= 3;
171 cinfo
->out_color_components
= 4;
173 default: /* else must be same colorspace as in file */
174 cinfo
->out_color_components
= cinfo
->num_components
;
177 cinfo
->output_components
= (cinfo
->quantize_colors
? 1 :
178 cinfo
->out_color_components
);
180 /* See if upsampler will want to emit more than one row at a time */
181 if (use_merged_upsample(cinfo
))
182 cinfo
->rec_outbuf_height
= cinfo
->max_v_samp_factor
;
184 cinfo
->rec_outbuf_height
= 1;
189 * Several decompression processes need to range-limit values to the range
190 * 0..MAXJSAMPLE; the input value may fall somewhat outside this range
191 * due to noise introduced by quantization, roundoff error, etc. These
192 * processes are inner loops and need to be as fast as possible. On most
193 * machines, particularly CPUs with pipelines or instruction prefetch,
194 * a (subscript-check-less) C table lookup
195 * x = sample_range_limit[x];
196 * is faster than explicit tests
198 * else if (x > MAXJSAMPLE) x = MAXJSAMPLE;
199 * These processes all use a common table prepared by the routine below.
201 * For most steps we can mathematically guarantee that the initial value
202 * of x is within MAXJSAMPLE+1 of the legal range, so a table running from
203 * -(MAXJSAMPLE+1) to 2*MAXJSAMPLE+1 is sufficient. But for the initial
204 * limiting step (just after the IDCT), a wildly out-of-range value is
205 * possible if the input data is corrupt. To avoid any chance of indexing
206 * off the end of memory and getting a bad-pointer trap, we perform the
207 * post-IDCT limiting thus:
208 * x = range_limit[x & MASK];
209 * where MASK is 2 bits wider than legal sample data, ie 10 bits for 8-bit
210 * samples. Under normal circumstances this is more than enough range and
211 * a correct output will be generated; with bogus input data the mask will
212 * cause wraparound, and we will safely generate a bogus-but-in-range output.
213 * For the post-IDCT step, we want to convert the data from signed to unsigned
214 * representation by adding CENTERJSAMPLE at the same time that we limit it.
215 * So the post-IDCT limiting table ends up looking like this:
216 * CENTERJSAMPLE,CENTERJSAMPLE+1,...,MAXJSAMPLE,
217 * MAXJSAMPLE (repeat 2*(MAXJSAMPLE+1)-CENTERJSAMPLE times),
218 * 0 (repeat 2*(MAXJSAMPLE+1)-CENTERJSAMPLE times),
219 * 0,1,...,CENTERJSAMPLE-1
220 * Negative inputs select values from the upper half of the table after
223 * We can save some space by overlapping the start of the post-IDCT table
224 * with the simpler range limiting table. The post-IDCT table begins at
225 * sample_range_limit + CENTERJSAMPLE.
227 * Note that the table is allocated in near data space on PCs; it's small
228 * enough and used often enough to justify this.
232 prepare_range_limit_table (j_decompress_ptr cinfo
)
233 /* Allocate and fill in the sample_range_limit table */
239 (*cinfo
->mem
->alloc_small
) ((j_common_ptr
) cinfo
, JPOOL_IMAGE
,
240 (5 * (MAXJSAMPLE
+1) + CENTERJSAMPLE
) * SIZEOF(JSAMPLE
));
241 table
+= (MAXJSAMPLE
+1); /* allow negative subscripts of simple table */
242 cinfo
->sample_range_limit
= table
;
243 /* First segment of "simple" table: limit[x] = 0 for x < 0 */
244 MEMZERO(table
- (MAXJSAMPLE
+1), (MAXJSAMPLE
+1) * SIZEOF(JSAMPLE
));
245 /* Main part of "simple" table: limit[x] = x */
246 for (i
= 0; i
<= MAXJSAMPLE
; i
++)
247 table
[i
] = (JSAMPLE
) i
;
248 table
+= CENTERJSAMPLE
; /* Point to where post-IDCT table starts */
249 /* End of simple table, rest of first half of post-IDCT table */
250 for (i
= CENTERJSAMPLE
; i
< 2*(MAXJSAMPLE
+1); i
++)
251 table
[i
] = MAXJSAMPLE
;
252 /* Second half of post-IDCT table */
253 MEMZERO(table
+ (2 * (MAXJSAMPLE
+1)),
254 (2 * (MAXJSAMPLE
+1) - CENTERJSAMPLE
) * SIZEOF(JSAMPLE
));
255 MEMCOPY(table
+ (4 * (MAXJSAMPLE
+1) - CENTERJSAMPLE
),
256 cinfo
->sample_range_limit
, CENTERJSAMPLE
* SIZEOF(JSAMPLE
));
261 * Master selection of decompression modules.
262 * This is done once at jpeg_start_decompress time. We determine
263 * which modules will be used and give them appropriate initialization calls.
264 * We also initialize the decompressor input side to begin consuming data.
266 * Since jpeg_read_header has finished, we know what is in the SOF
267 * and (first) SOS markers. We also have all the application parameter
272 master_selection (j_decompress_ptr cinfo
)
274 my_master_ptr master
= (my_master_ptr
) cinfo
->master
;
275 boolean use_c_buffer
;
277 JDIMENSION jd_samplesperrow
;
279 /* For now, precision must match compiled-in value... */
280 if (cinfo
->data_precision
!= BITS_IN_JSAMPLE
)
281 ERREXIT1(cinfo
, JERR_BAD_PRECISION
, cinfo
->data_precision
);
283 /* Initialize dimensions and other stuff */
284 jpeg_calc_output_dimensions(cinfo
);
285 prepare_range_limit_table(cinfo
);
287 /* Sanity check on image dimensions */
288 if (cinfo
->output_height
<= 0 || cinfo
->output_width
<= 0 ||
289 cinfo
->out_color_components
<= 0)
290 ERREXIT(cinfo
, JERR_EMPTY_IMAGE
);
292 /* Width of an output scanline must be representable as JDIMENSION. */
293 samplesperrow
= (long) cinfo
->output_width
* (long) cinfo
->out_color_components
;
294 jd_samplesperrow
= (JDIMENSION
) samplesperrow
;
295 if ((long) jd_samplesperrow
!= samplesperrow
)
296 ERREXIT(cinfo
, JERR_WIDTH_OVERFLOW
);
298 /* Initialize my private state */
299 master
->pass_number
= 0;
300 master
->using_merged_upsample
= use_merged_upsample(cinfo
);
302 /* Color quantizer selection */
303 master
->quantizer_1pass
= NULL
;
304 master
->quantizer_2pass
= NULL
;
305 /* No mode changes if not using buffered-image mode. */
306 if (! cinfo
->quantize_colors
|| ! cinfo
->buffered_image
) {
307 cinfo
->enable_1pass_quant
= FALSE
;
308 cinfo
->enable_external_quant
= FALSE
;
309 cinfo
->enable_2pass_quant
= FALSE
;
311 if (cinfo
->quantize_colors
) {
312 if (cinfo
->raw_data_out
)
313 ERREXIT(cinfo
, JERR_NOTIMPL
);
314 /* 2-pass quantizer only works in 3-component color space. */
315 if (cinfo
->out_color_components
!= 3) {
316 cinfo
->enable_1pass_quant
= TRUE
;
317 cinfo
->enable_external_quant
= FALSE
;
318 cinfo
->enable_2pass_quant
= FALSE
;
319 cinfo
->colormap
= NULL
;
320 } else if (cinfo
->colormap
!= NULL
) {
321 cinfo
->enable_external_quant
= TRUE
;
322 } else if (cinfo
->two_pass_quantize
) {
323 cinfo
->enable_2pass_quant
= TRUE
;
325 cinfo
->enable_1pass_quant
= TRUE
;
328 if (cinfo
->enable_1pass_quant
) {
329 #ifdef QUANT_1PASS_SUPPORTED
330 jinit_1pass_quantizer(cinfo
);
331 master
->quantizer_1pass
= cinfo
->cquantize
;
333 ERREXIT(cinfo
, JERR_NOT_COMPILED
);
337 /* We use the 2-pass code to map to external colormaps. */
338 if (cinfo
->enable_2pass_quant
|| cinfo
->enable_external_quant
) {
339 #ifdef QUANT_2PASS_SUPPORTED
340 jinit_2pass_quantizer(cinfo
);
341 master
->quantizer_2pass
= cinfo
->cquantize
;
343 ERREXIT(cinfo
, JERR_NOT_COMPILED
);
346 /* If both quantizers are initialized, the 2-pass one is left active;
347 * this is necessary for starting with quantization to an external map.
351 /* Post-processing: in particular, color conversion first */
352 if (! cinfo
->raw_data_out
) {
353 if (master
->using_merged_upsample
) {
354 #ifdef UPSAMPLE_MERGING_SUPPORTED
355 jinit_merged_upsampler(cinfo
); /* does color conversion too */
357 ERREXIT(cinfo
, JERR_NOT_COMPILED
);
360 jinit_color_deconverter(cinfo
);
361 jinit_upsampler(cinfo
);
363 jinit_d_post_controller(cinfo
, cinfo
->enable_2pass_quant
);
366 jinit_inverse_dct(cinfo
);
367 /* Entropy decoding: either Huffman or arithmetic coding. */
368 if (cinfo
->arith_code
)
369 jinit_arith_decoder(cinfo
);
371 jinit_huff_decoder(cinfo
);
374 /* Initialize principal buffer controllers. */
375 use_c_buffer
= cinfo
->inputctl
->has_multiple_scans
|| cinfo
->buffered_image
;
376 jinit_d_coef_controller(cinfo
, use_c_buffer
);
378 if (! cinfo
->raw_data_out
)
379 jinit_d_main_controller(cinfo
, FALSE
/* never need full buffer here */);
381 /* We can now tell the memory manager to allocate virtual arrays. */
382 (*cinfo
->mem
->realize_virt_arrays
) ((j_common_ptr
) cinfo
);
384 /* Initialize input side of decompressor to consume first scan. */
385 (*cinfo
->inputctl
->start_input_pass
) (cinfo
);
387 #ifdef D_MULTISCAN_FILES_SUPPORTED
388 /* If jpeg_start_decompress will read the whole file, initialize
389 * progress monitoring appropriately. The input step is counted
392 if (cinfo
->progress
!= NULL
&& ! cinfo
->buffered_image
&&
393 cinfo
->inputctl
->has_multiple_scans
) {
395 /* Estimate number of scans to set pass_limit. */
396 if (cinfo
->progressive_mode
) {
397 /* Arbitrarily estimate 2 interleaved DC scans + 3 AC scans/component. */
398 nscans
= 2 + 3 * cinfo
->num_components
;
400 /* For a nonprogressive multiscan file, estimate 1 scan per component. */
401 nscans
= cinfo
->num_components
;
403 cinfo
->progress
->pass_counter
= 0L;
404 cinfo
->progress
->pass_limit
= (long) cinfo
->total_iMCU_rows
* nscans
;
405 cinfo
->progress
->completed_passes
= 0;
406 cinfo
->progress
->total_passes
= (cinfo
->enable_2pass_quant
? 3 : 2);
407 /* Count the input pass as done */
408 master
->pass_number
++;
410 #endif /* D_MULTISCAN_FILES_SUPPORTED */
416 * This is called at the beginning of each output pass. We determine which
417 * modules will be active during this pass and give them appropriate
418 * start_pass calls. We also set is_dummy_pass to indicate whether this
419 * is a "real" output pass or a dummy pass for color quantization.
420 * (In the latter case, jdapistd.c will crank the pass to completion.)
424 prepare_for_output_pass (j_decompress_ptr cinfo
)
426 my_master_ptr master
= (my_master_ptr
) cinfo
->master
;
428 if (master
->pub
.is_dummy_pass
) {
429 #ifdef QUANT_2PASS_SUPPORTED
430 /* Final pass of 2-pass quantization */
431 master
->pub
.is_dummy_pass
= FALSE
;
432 (*cinfo
->cquantize
->start_pass
) (cinfo
, FALSE
);
433 (*cinfo
->post
->start_pass
) (cinfo
, JBUF_CRANK_DEST
);
434 (*cinfo
->main
->start_pass
) (cinfo
, JBUF_CRANK_DEST
);
436 ERREXIT(cinfo
, JERR_NOT_COMPILED
);
437 #endif /* QUANT_2PASS_SUPPORTED */
439 if (cinfo
->quantize_colors
&& cinfo
->colormap
== NULL
) {
440 /* Select new quantization method */
441 if (cinfo
->two_pass_quantize
&& cinfo
->enable_2pass_quant
) {
442 cinfo
->cquantize
= master
->quantizer_2pass
;
443 master
->pub
.is_dummy_pass
= TRUE
;
444 } else if (cinfo
->enable_1pass_quant
) {
445 cinfo
->cquantize
= master
->quantizer_1pass
;
447 ERREXIT(cinfo
, JERR_MODE_CHANGE
);
450 (*cinfo
->idct
->start_pass
) (cinfo
);
451 (*cinfo
->coef
->start_output_pass
) (cinfo
);
452 if (! cinfo
->raw_data_out
) {
453 if (! master
->using_merged_upsample
)
454 (*cinfo
->cconvert
->start_pass
) (cinfo
);
455 (*cinfo
->upsample
->start_pass
) (cinfo
);
456 if (cinfo
->quantize_colors
)
457 (*cinfo
->cquantize
->start_pass
) (cinfo
, master
->pub
.is_dummy_pass
);
458 (*cinfo
->post
->start_pass
) (cinfo
,
459 (master
->pub
.is_dummy_pass
? JBUF_SAVE_AND_PASS
: JBUF_PASS_THRU
));
460 (*cinfo
->main
->start_pass
) (cinfo
, JBUF_PASS_THRU
);
464 /* Set up progress monitor's pass info if present */
465 if (cinfo
->progress
!= NULL
) {
466 cinfo
->progress
->completed_passes
= master
->pass_number
;
467 cinfo
->progress
->total_passes
= master
->pass_number
+
468 (master
->pub
.is_dummy_pass
? 2 : 1);
469 /* In buffered-image mode, we assume one more output pass if EOI not
470 * yet reached, but no more passes if EOI has been reached.
472 if (cinfo
->buffered_image
&& ! cinfo
->inputctl
->eoi_reached
) {
473 cinfo
->progress
->total_passes
+= (cinfo
->enable_2pass_quant
? 2 : 1);
480 * Finish up at end of an output pass.
484 finish_output_pass (j_decompress_ptr cinfo
)
486 my_master_ptr master
= (my_master_ptr
) cinfo
->master
;
488 if (cinfo
->quantize_colors
)
489 (*cinfo
->cquantize
->finish_pass
) (cinfo
);
490 master
->pass_number
++;
494 #ifdef D_MULTISCAN_FILES_SUPPORTED
497 * Switch to a new external colormap between output passes.
501 jpeg_new_colormap (j_decompress_ptr cinfo
)
503 my_master_ptr master
= (my_master_ptr
) cinfo
->master
;
505 /* Prevent application from calling me at wrong times */
506 if (cinfo
->global_state
!= DSTATE_BUFIMAGE
)
507 ERREXIT1(cinfo
, JERR_BAD_STATE
, cinfo
->global_state
);
509 if (cinfo
->quantize_colors
&& cinfo
->enable_external_quant
&&
510 cinfo
->colormap
!= NULL
) {
511 /* Select 2-pass quantizer for external colormap use */
512 cinfo
->cquantize
= master
->quantizer_2pass
;
513 /* Notify quantizer of colormap change */
514 (*cinfo
->cquantize
->new_color_map
) (cinfo
);
515 master
->pub
.is_dummy_pass
= FALSE
; /* just in case */
517 ERREXIT(cinfo
, JERR_MODE_CHANGE
);
520 #endif /* D_MULTISCAN_FILES_SUPPORTED */
524 * Initialize master decompression control and select active modules.
525 * This is performed at the start of jpeg_start_decompress.
529 jinit_master_decompress (j_decompress_ptr cinfo
)
531 my_master_ptr master
;
533 master
= (my_master_ptr
)
534 (*cinfo
->mem
->alloc_small
) ((j_common_ptr
) cinfo
, JPOOL_IMAGE
,
535 SIZEOF(my_decomp_master
));
536 cinfo
->master
= &master
->pub
;
537 master
->pub
.prepare_for_output_pass
= prepare_for_output_pass
;
538 master
->pub
.finish_output_pass
= finish_output_pass
;
540 master
->pub
.is_dummy_pass
= FALSE
;
542 master_selection(cinfo
);