compiler/libjpeg/main/jdmaster.c

   1 /*
   2     $Id$
   3 */
   4
   5 /*
   6  * jdmaster.c
   7  *
   8  * Copyright (C) 1991-1998, Thomas G. Lane.
   9  * This file is part of the Independent JPEG Group's software.
  10  * For conditions of distribution and use, see the accompanying README file.
  11  *
  12  * This file contains master control logic for the JPEG decompressor.
  13  * These routines are concerned with selecting the modules to be executed
  14  * and with determining the number of passes and the work to be done in each
  15  * pass.
  16  */
  17
  18 #define JPEG_INTERNALS
  19 #include "jinclude.h"
  20 #include "jpeglib.h"
  21
  22
  23 /* Private state */
  24
  25 typedef struct {
  26   struct jpeg_decomp_master pub; /* public fields */
  27
  28   int pass_number;              /* # of passes completed */
  29
  30   boolean using_merged_upsample; /* TRUE if using merged upsample/cconvert */
  31
  32   /* Saved references to initialized quantizer modules,
  33    * in case we need to switch modes.
  34    */
  35   struct jpeg_color_quantizer * quantizer_1pass;
  36   struct jpeg_color_quantizer * quantizer_2pass;
  37 } my_decomp_master;
  38
  39 typedef my_decomp_master * my_master_ptr;
  40
  41
  42 /*
  43  * Determine whether merged upsample/color conversion should be used.
  44  * CRUCIAL: this must match the actual capabilities of jdmerge.c!
  45  */
  46
  47 LOCAL(boolean)
  48 use_merged_upsample (j_decompress_ptr cinfo)
  49 {
  50 #ifdef UPSAMPLE_MERGING_SUPPORTED
  51   /* Merging is the equivalent of plain box-filter upsampling */
  52   if (cinfo->do_fancy_upsampling || cinfo->CCIR601_sampling)
  53     return FALSE;
  54   /* jdmerge.c only supports YCC=>RGB color conversion */
  55   if (cinfo->jpeg_color_space != JCS_YCbCr || cinfo->num_components != 3 ||
  56       cinfo->out_color_space != JCS_RGB ||
  57       cinfo->out_color_components != RGB_PIXELSIZE)
  58     return FALSE;
  59   /* and it only handles 2h1v or 2h2v sampling ratios */
  60   if (cinfo->comp_info[0].h_samp_factor != 2 ||
  61       cinfo->comp_info[1].h_samp_factor != 1 ||
  62       cinfo->comp_info[2].h_samp_factor != 1 ||
  63       cinfo->comp_info[0].v_samp_factor >  2 ||
  64       cinfo->comp_info[1].v_samp_factor != 1 ||
  65       cinfo->comp_info[2].v_samp_factor != 1)
  66     return FALSE;
  67   /* furthermore, it doesn't work if each component has been
  68      processed differently */
  69   if (cinfo->comp_info[0].codec_data_unit != cinfo->min_codec_data_unit ||
  70       cinfo->comp_info[1].codec_data_unit != cinfo->min_codec_data_unit ||
  71       cinfo->comp_info[2].codec_data_unit != cinfo->min_codec_data_unit)
  72     return FALSE;
  73   /* ??? also need to test for upsample-time rescaling, when & if supported */
  74   return TRUE;                  /* by golly, it'll work... */
  75 #else
  76   return FALSE;
  77 #endif
  78 }
  79
  80
  81 /*
  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!
  86  */
  87
  88 JGLOBAL(void)
  89 jpeg_calc_output_dimensions (j_decompress_ptr cinfo)
  90 /* Do computations that are needed before master selection phase */
  91 {
  92   /* Prevent application from calling me at wrong times */
  93   if (cinfo->global_state != DSTATE_READY)
  94     ERREXIT1(cinfo, JERR_BAD_STATE, cinfo->global_state);
  95
  96   (*cinfo->codec->calc_output_dimensions) (cinfo);
  97
  98   /* Report number of components in selected colorspace. */
  99   /* Probably this should be in the color conversion module... */
 100   switch (cinfo->out_color_space) {
 101   case JCS_GRAYSCALE:
 102     cinfo->out_color_components = 1;
 103     break;
 104   case JCS_RGB:
 105 #if RGB_PIXELSIZE != 3
 106     cinfo->out_color_components = RGB_PIXELSIZE;
 107     break;
 108 #endif /* else share code with YCbCr */
 109   case JCS_YCbCr:
 110     cinfo->out_color_components = 3;
 111     break;
 112   case JCS_CMYK:
 113   case JCS_YCCK:
 114     cinfo->out_color_components = 4;
 115     break;
 116   default:                      /* else must be same colorspace as in file */
 117     cinfo->out_color_components = cinfo->num_components;
 118     break;
 119   }
 120   cinfo->output_components = (cinfo->quantize_colors ? 1 :
 121                               cinfo->out_color_components);
 122
 123   /* See if upsampler will want to emit more than one row at a time */
 124   if (use_merged_upsample(cinfo))
 125     cinfo->rec_outbuf_height = cinfo->max_v_samp_factor;
 126   else
 127     cinfo->rec_outbuf_height = 1;
 128 }
 129
 130
 131 /*
 132  * Several decompression processes need to range-limit values to the range
 133  * 0..MAXJSAMPLE; the input value may fall somewhat outside this range
 134  * due to noise introduced by quantization, roundoff error, etc.  These
 135  * processes are inner loops and need to be as fast as possible.  On most
 136  * machines, particularly CPUs with pipelines or instruction prefetch,
 137  * a (subscript-check-less) C table lookup
 138  *              x = sample_range_limit[x];
 139  * is faster than explicit tests
 140  *              if (x < 0)  x = 0;
 141  *              else if (x > MAXJSAMPLE)  x = MAXJSAMPLE;
 142  * These processes all use a common table prepared by the routine below.
 143  *
 144  * For most steps we can mathematically guarantee that the initial value
 145  * of x is within MAXJSAMPLE+1 of the legal range, so a table running from
 146  * -(MAXJSAMPLE+1) to 2*MAXJSAMPLE+1 is sufficient.  But for the initial
 147  * limiting step (just after the IDCT), a wildly out-of-range value is
 148  * possible if the input data is corrupt.  To avoid any chance of indexing
 149  * off the end of memory and getting a bad-pointer trap, we perform the
 150  * post-IDCT limiting thus:
 151  *              x = range_limit[x & MASK];
 152  * where MASK is 2 bits wider than legal sample data, ie 10 bits for 8-bit
 153  * samples.  Under normal circumstances this is more than enough range and
 154  * a correct output will be generated; with bogus input data the mask will
 155  * cause wraparound, and we will safely generate a bogus-but-in-range output.
 156  * For the post-IDCT step, we want to convert the data from signed to unsigned
 157  * representation by adding CENTERJSAMPLE at the same time that we limit it.
 158  * So the post-IDCT limiting table ends up looking like this:
 159  *   CENTERJSAMPLE,CENTERJSAMPLE+1,...,MAXJSAMPLE,
 160  *   MAXJSAMPLE (repeat 2*(MAXJSAMPLE+1)-CENTERJSAMPLE times),
 161  *   0          (repeat 2*(MAXJSAMPLE+1)-CENTERJSAMPLE times),
 162  *   0,1,...,CENTERJSAMPLE-1
 163  * Negative inputs select values from the upper half of the table after
 164  * masking.
 165  *
 166  * We can save some space by overlapping the start of the post-IDCT table
 167  * with the simpler range limiting table.  The post-IDCT table begins at
 168  * sample_range_limit + CENTERJSAMPLE.
 169  *
 170  * Note that the table is allocated in near data space on PCs; it's small
 171  * enough and used often enough to justify this.
 172  */
 173
 174 LOCAL(void)
 175 prepare_range_limit_table (j_decompress_ptr cinfo)
 176 /* Allocate and fill in the sample_range_limit table */
 177 {
 178   JSAMPLE * table;
 179   int i;
 180
 181   table = (JSAMPLE *)
 182     (*cinfo->mem->alloc_small) ((j_common_ptr) cinfo, JPOOL_IMAGE,
 183                 (5 * (MAXJSAMPLE+1) + CENTERJSAMPLE) * SIZEOF(JSAMPLE));
 184   table += (MAXJSAMPLE+1);      /* allow negative subscripts of simple table */
 185   cinfo->sample_range_limit = table;
 186   /* First segment of "simple" table: limit[x] = 0 for x < 0 */
 187   MEMZERO(table - (MAXJSAMPLE+1), (MAXJSAMPLE+1) * SIZEOF(JSAMPLE));
 188   /* Main part of "simple" table: limit[x] = x */
 189   for (i = 0; i <= MAXJSAMPLE; i++)
 190     table[i] = (JSAMPLE) i;
 191   table += CENTERJSAMPLE;       /* Point to where post-IDCT table starts */
 192   /* End of simple table, rest of first half of post-IDCT table */
 193   for (i = CENTERJSAMPLE; i < 2*(MAXJSAMPLE+1); i++)
 194     table[i] = MAXJSAMPLE;
 195   /* Second half of post-IDCT table */
 196   MEMZERO(table + (2 * (MAXJSAMPLE+1)),
 197           (2 * (MAXJSAMPLE+1) - CENTERJSAMPLE) * SIZEOF(JSAMPLE));
 198   MEMCOPY(table + (4 * (MAXJSAMPLE+1) - CENTERJSAMPLE),
 199           cinfo->sample_range_limit, CENTERJSAMPLE * SIZEOF(JSAMPLE));
 200 }
 201
 202
 203 /*
 204  * Master selection of decompression modules.
 205  * This is done once at jpeg_start_decompress time.  We determine
 206  * which modules will be used and give them appropriate initialization calls.
 207  * We also initialize the decompressor input side to begin consuming data.
 208  *
 209  * Since jpeg_read_header has finished, we know what is in the SOF
 210  * and (first) SOS markers.  We also have all the application parameter
 211  * settings.
 212  */
 213
 214 LOCAL(void)
 215 master_selection (j_decompress_ptr cinfo)
 216 {
 217   my_master_ptr master = (my_master_ptr) cinfo->master;
 218   long samplesperrow;
 219   JDIMENSION jd_samplesperrow;
 220
 221   /* Initialize dimensions and other stuff */
 222   jpeg_calc_output_dimensions(cinfo);
 223   prepare_range_limit_table(cinfo);
 224
 225   /* Width of an output scanline must be representable as JDIMENSION. */
 226   samplesperrow = (long) cinfo->output_width * (long) cinfo->out_color_components;
 227   jd_samplesperrow = (JDIMENSION) samplesperrow;
 228   if ((long) jd_samplesperrow != samplesperrow)
 229     ERREXIT(cinfo, JERR_WIDTH_OVERFLOW);
 230
 231   /* Initialize my private state */
 232   master->pass_number = 0;
 233   master->using_merged_upsample = use_merged_upsample(cinfo);
 234
 235   /* Color quantizer selection */
 236   master->quantizer_1pass = NULL;
 237   master->quantizer_2pass = NULL;
 238   /* No mode changes if not using buffered-image mode. */
 239   if (! cinfo->quantize_colors || ! cinfo->buffered_image) {
 240     cinfo->enable_1pass_quant = FALSE;
 241     cinfo->enable_external_quant = FALSE;
 242     cinfo->enable_2pass_quant = FALSE;
 243   }
 244   if (cinfo->quantize_colors) {
 245     if (cinfo->raw_data_out)
 246       ERREXIT(cinfo, JERR_NOTIMPL);
 247     /* 2-pass quantizer only works in 3-component color space. */
 248     if (cinfo->out_color_components != 3) {
 249       cinfo->enable_1pass_quant = TRUE;
 250       cinfo->enable_external_quant = FALSE;
 251       cinfo->enable_2pass_quant = FALSE;
 252       cinfo->colormap = NULL;
 253     } else if (cinfo->colormap != NULL) {
 254       cinfo->enable_external_quant = TRUE;
 255     } else if (cinfo->two_pass_quantize) {
 256       cinfo->enable_2pass_quant = TRUE;
 257     } else {
 258       cinfo->enable_1pass_quant = TRUE;
 259     }
 260
 261     if (cinfo->enable_1pass_quant) {
 262 #ifdef QUANT_1PASS_SUPPORTED
 263       jinit_1pass_quantizer(cinfo);
 264       master->quantizer_1pass = cinfo->cquantize;
 265 #else
 266       ERREXIT(cinfo, JERR_NOT_COMPILED);
 267 #endif
 268     }
 269
 270     /* We use the 2-pass code to map to external colormaps. */
 271     if (cinfo->enable_2pass_quant || cinfo->enable_external_quant) {
 272 #ifdef QUANT_2PASS_SUPPORTED
 273       jinit_2pass_quantizer(cinfo);
 274       master->quantizer_2pass = cinfo->cquantize;
 275 #else
 276       ERREXIT(cinfo, JERR_NOT_COMPILED);
 277 #endif
 278     }
 279     /* If both quantizers are initialized, the 2-pass one is left active;
 280      * this is necessary for starting with quantization to an external map.
 281      */
 282   }
 283
 284   /* Post-processing: in particular, color conversion first */
 285   if (! cinfo->raw_data_out) {
 286     if (master->using_merged_upsample) {
 287 #ifdef UPSAMPLE_MERGING_SUPPORTED
 288       jinit_merged_upsampler(cinfo); /* does color conversion too */
 289 #else
 290       ERREXIT(cinfo, JERR_NOT_COMPILED);
 291 #endif
 292     } else {
 293       jinit_color_deconverter(cinfo);
 294       jinit_upsampler(cinfo);
 295     }
 296     jinit_d_post_controller(cinfo, cinfo->enable_2pass_quant);
 297   }
 298
 299   /* Initialize principal buffer controllers. */
 300   if (! cinfo->raw_data_out)
 301     jinit_d_main_controller(cinfo, FALSE /* never need full buffer here */);
 302
 303   /* We can now tell the memory manager to allocate virtual arrays. */
 304   (*cinfo->mem->realize_virt_arrays) ((j_common_ptr) cinfo);
 305
 306   /* Initialize input side of decompressor to consume first scan. */
 307   (*cinfo->inputctl->start_input_pass) (cinfo);
 308
 309 #ifdef D_MULTISCAN_FILES_SUPPORTED
 310   /* If jpeg_start_decompress will read the whole file, initialize
 311    * progress monitoring appropriately.  The input step is counted
 312    * as one pass.
 313    */
 314   if (cinfo->progress != NULL && ! cinfo->buffered_image &&
 315       cinfo->inputctl->has_multiple_scans) {
 316     int nscans;
 317     /* Estimate number of scans to set pass_limit. */
 318     if (cinfo->process == JPROC_PROGRESSIVE) {
 319       /* Arbitrarily estimate 2 interleaved DC scans + 3 AC scans/component. */
 320       nscans = 2 + 3 * cinfo->num_components;
 321     } else {
 322       /* For a nonprogressive multiscan file, estimate 1 scan per component. */
 323       nscans = cinfo->num_components;
 324     }
 325     cinfo->progress->pass_counter = 0L;
 326     cinfo->progress->pass_limit = (long) cinfo->total_iMCU_rows * nscans;
 327     cinfo->progress->completed_passes = 0;
 328     cinfo->progress->total_passes = (cinfo->enable_2pass_quant ? 3 : 2);
 329     /* Count the input pass as done */
 330     master->pass_number++;
 331   }
 332 #endif /* D_MULTISCAN_FILES_SUPPORTED */
 333 }
 334
 335
 336 /*
 337  * Per-pass setup.
 338  * This is called at the beginning of each output pass.  We determine which
 339  * modules will be active during this pass and give them appropriate
 340  * start_pass calls.  We also set is_dummy_pass to indicate whether this
 341  * is a "real" output pass or a dummy pass for color quantization.
 342  * (In the latter case, jdapistd.c will crank the pass to completion.)
 343  */
 344
 345 METHODDEF(void)
 346 prepare_for_output_pass (j_decompress_ptr cinfo)
 347 {
 348   my_master_ptr master = (my_master_ptr) cinfo->master;
 349
 350   if (master->pub.is_dummy_pass) {
 351 #ifdef QUANT_2PASS_SUPPORTED
 352     /* Final pass of 2-pass quantization */
 353     master->pub.is_dummy_pass = FALSE;
 354     (*cinfo->cquantize->start_pass) (cinfo, FALSE);
 355     (*cinfo->post->start_pass) (cinfo, JBUF_CRANK_DEST);
 356     (*cinfo->main->start_pass) (cinfo, JBUF_CRANK_DEST);
 357 #else
 358     ERREXIT(cinfo, JERR_NOT_COMPILED);
 359 #endif /* QUANT_2PASS_SUPPORTED */
 360   } else {
 361     if (cinfo->quantize_colors && cinfo->colormap == NULL) {
 362       /* Select new quantization method */
 363       if (cinfo->two_pass_quantize && cinfo->enable_2pass_quant) {
 364         cinfo->cquantize = master->quantizer_2pass;
 365         master->pub.is_dummy_pass = TRUE;
 366       } else if (cinfo->enable_1pass_quant) {
 367         cinfo->cquantize = master->quantizer_1pass;
 368       } else {
 369         ERREXIT(cinfo, JERR_MODE_CHANGE);
 370       }
 371     }
 372     (*cinfo->codec->start_output_pass) (cinfo);
 373     if (! cinfo->raw_data_out) {
 374       if (! master->using_merged_upsample)
 375         (*cinfo->cconvert->start_pass) (cinfo);
 376       (*cinfo->upsample->start_pass) (cinfo);
 377       if (cinfo->quantize_colors)
 378         (*cinfo->cquantize->start_pass) (cinfo, master->pub.is_dummy_pass);
 379       (*cinfo->post->start_pass) (cinfo,
 380             (master->pub.is_dummy_pass ? JBUF_SAVE_AND_PASS : JBUF_PASS_THRU));
 381       (*cinfo->main->start_pass) (cinfo, JBUF_PASS_THRU);
 382     }
 383   }
 384
 385   /* Set up progress monitor's pass info if present */
 386   if (cinfo->progress != NULL) {
 387     cinfo->progress->completed_passes = master->pass_number;
 388     cinfo->progress->total_passes = master->pass_number +
 389                                     (master->pub.is_dummy_pass ? 2 : 1);
 390     /* In buffered-image mode, we assume one more output pass if EOI not
 391      * yet reached, but no more passes if EOI has been reached.
 392      */
 393     if (cinfo->buffered_image && ! cinfo->inputctl->eoi_reached) {
 394       cinfo->progress->total_passes += (cinfo->enable_2pass_quant ? 2 : 1);
 395     }
 396   }
 397 }
 398
 399
 400 /*
 401  * Finish up at end of an output pass.
 402  */
 403
 404 METHODDEF(void)
 405 finish_output_pass (j_decompress_ptr cinfo)
 406 {
 407   my_master_ptr master = (my_master_ptr) cinfo->master;
 408
 409   if (cinfo->quantize_colors)
 410     (*cinfo->cquantize->finish_pass) (cinfo);
 411   master->pass_number++;
 412 }
 413
 414
 415 #ifdef D_MULTISCAN_FILES_SUPPORTED
 416
 417 /*
 418  * Switch to a new external colormap between output passes.
 419  */
 420
 421 JGLOBAL(void)
 422 jpeg_new_colormap (j_decompress_ptr cinfo)
 423 {
 424   my_master_ptr master = (my_master_ptr) cinfo->master;
 425
 426   /* Prevent application from calling me at wrong times */
 427   if (cinfo->global_state != DSTATE_BUFIMAGE)
 428     ERREXIT1(cinfo, JERR_BAD_STATE, cinfo->global_state);
 429
 430   if (cinfo->quantize_colors && cinfo->enable_external_quant &&
 431       cinfo->colormap != NULL) {
 432     /* Select 2-pass quantizer for external colormap use */
 433     cinfo->cquantize = master->quantizer_2pass;
 434     /* Notify quantizer of colormap change */
 435     (*cinfo->cquantize->new_color_map) (cinfo);
 436     master->pub.is_dummy_pass = FALSE; /* just in case */
 437   } else
 438     ERREXIT(cinfo, JERR_MODE_CHANGE);
 439 }
 440
 441 #endif /* D_MULTISCAN_FILES_SUPPORTED */
 442
 443
 444 /*
 445  * Initialize master decompression control and select active modules.
 446  * This is performed at the start of jpeg_start_decompress.
 447  */
 448
 449 JGLOBAL(void)
 450 jinit_master_decompress (j_decompress_ptr cinfo)
 451 {
 452   my_master_ptr master;
 453
 454   master = (my_master_ptr)
 455       (*cinfo->mem->alloc_small) ((j_common_ptr) cinfo, JPOOL_IMAGE,
 456                                   SIZEOF(my_decomp_master));
 457   cinfo->master = (struct jpeg_decomp_master *) master;
 458   master->pub.prepare_for_output_pass = prepare_for_output_pass;
 459   master->pub.finish_output_pass = finish_output_pass;
 460
 461   master->pub.is_dummy_pass = FALSE;
 462
 463   master_selection(cinfo);
 464 }