0N/A * reserved comment block 0N/A * DO NOT REMOVE OR ALTER! 0N/A * Copyright (C) 1994-1996, Thomas G. Lane. 0N/A * This file is part of the Independent JPEG Group's software. 0N/A * For conditions of distribution and use, see the accompanying README file. 0N/A * This file contains the main buffer controller for decompression. 0N/A * The main buffer lies between the JPEG decompressor proper and the 0N/A * post-processor; it holds downsampled data in the JPEG colorspace. 0N/A * Note that this code is bypassed in raw-data mode, since the application 0N/A * supplies the equivalent of the main buffer in that case. 0N/A * In the current system design, the main buffer need never be a full-image 0N/A * buffer; any full-height buffers will be found inside the coefficient or 0N/A * postprocessing controllers. Nonetheless, the main controller is not 0N/A * trivial. Its responsibility is to provide context rows for upsampling/ 0N/A * rescaling, and doing this in an efficient fashion is a bit tricky. 0N/A * Postprocessor input data is counted in "row groups". A row group 0N/A * is defined to be (v_samp_factor * DCT_scaled_size / min_DCT_scaled_size) 0N/A * sample rows of each component. (We require DCT_scaled_size values to be 0N/A * chosen such that these numbers are integers. In practice DCT_scaled_size 0N/A * values will likely be powers of two, so we actually have the stronger 0N/A * condition that DCT_scaled_size / min_DCT_scaled_size is an integer.) 0N/A * Upsampling will typically produce max_v_samp_factor pixel rows from each 0N/A * row group (times any additional scale factor that the upsampler is 0N/A * The coefficient controller will deliver data to us one iMCU row at a time; 0N/A * each iMCU row contains v_samp_factor * DCT_scaled_size sample rows, or 0N/A * exactly min_DCT_scaled_size row groups. (This amount of data corresponds 0N/A * to one row of MCUs when the image is fully interleaved.) Note that the 0N/A * number of sample rows varies across components, but the number of row 0N/A * groups does not. Some garbage sample rows may be included in the last iMCU 0N/A * row at the bottom of the image. 0N/A * Depending on the vertical scaling algorithm used, the upsampler may need 0N/A * access to the sample row(s) above and below its current input row group. 0N/A * The upsampler is required to set need_context_rows TRUE at global selection 0N/A * time if so. When need_context_rows is FALSE, this controller can simply 0N/A * obtain one iMCU row at a time from the coefficient controller and dole it 0N/A * out as row groups to the postprocessor. 0N/A * When need_context_rows is TRUE, this controller guarantees that the buffer 0N/A * passed to postprocessing contains at least one row group's worth of samples 0N/A * above and below the row group(s) being processed. Note that the context 0N/A * rows "above" the first passed row group appear at negative row offsets in 0N/A * the passed buffer. At the top and bottom of the image, the required 0N/A * context rows are manufactured by duplicating the first or last real sample 0N/A * row; this avoids having special cases in the upsampling inner loops. 0N/A * The amount of context is fixed at one row group just because that's a 0N/A * convenient number for this controller to work with. The existing 0N/A * upsamplers really only need one sample row of context. An upsampler 0N/A * supporting arbitrary output rescaling might wish for more than one row 0N/A * group of context when shrinking the image; tough, we don't handle that. 0N/A * (This is justified by the assumption that downsizing will be handled mostly 0N/A * by adjusting the DCT_scaled_size values, so that the actual scale factor at 0N/A * the upsample step needn't be much less than one.) 0N/A * To provide the desired context, we have to retain the last two row groups 0N/A * of one iMCU row while reading in the next iMCU row. (The last row group 0N/A * can't be processed until we have another row group for its below-context, 0N/A * and so we have to save the next-to-last group too for its above-context.) 0N/A * We could do this most simply by copying data around in our buffer, but 0N/A * that'd be very slow. We can avoid copying any data by creating a rather 0N/A * strange pointer structure. Here's how it works. We allocate a workspace 0N/A * consisting of M+2 row groups (where M = min_DCT_scaled_size is the number 0N/A * of row groups per iMCU row). We create two sets of redundant pointers to 0N/A * the workspace. Labeling the physical row groups 0 to M+1, the synthesized 0N/A * pointer lists look like this: 0N/A * master pointer --> 0 master pointer --> 0 0N/A * We read alternate iMCU rows using each master pointer; thus the last two 0N/A * row groups of the previous iMCU row remain un-overwritten in the workspace. 0N/A * The pointer lists are set up so that the required context rows appear to 0N/A * be adjacent to the proper places when we pass the pointer lists to the 0N/A * The above pictures describe the normal state of the pointer lists. 0N/A * At top and bottom of the image, we diddle the pointer lists to duplicate 0N/A * the first or last sample row as necessary (this is cheaper than copying 0N/A * sample rows around). 0N/A * This scheme breaks down if M < 2, ie, min_DCT_scaled_size is 1. In that 0N/A * situation each iMCU row provides only one row group so the buffering logic 0N/A * must be different (eg, we must read two iMCU rows before we can emit the 0N/A * first row group). For now, we simply do not support providing context 0N/A * rows when min_DCT_scaled_size is 1. That combination seems unlikely to 0N/A * be worth providing --- if someone wants a 1/8th-size preview, they probably 0N/A * want it quick and dirty, so a context-free upsampler is sufficient. 0N/A/* Private buffer controller object */ 0N/A /* Pointer to allocated workspace (M or M+2 row groups). */ 0N/A /* Remaining fields are only used in the context case. */ 0N/A /* These are the master pointers to the funny-order pointer lists. */ 0N/A int whichptr;
/* indicates which pointer set is now in use */ 0N/A/* context_state values: */ 0N/A/* Forward declarations */ 0N/A/* Allocate space for the funny pointer lists. 0N/A * This is done only once, not once per pass. 0N/A /* Get top-level space for component array pointers. 0N/A * We alloc both arrays with one call to save a few cycles. 0N/A /* Get space for pointer lists --- M+4 row groups in each list. 0N/A * We alloc both pointer lists with one call to save a few cycles. 0N/A/* Create the funny pointer lists discussed in the comments above. 0N/A * The actual workspace is already allocated (in main->buffer), 0N/A * and the space for the pointer lists is allocated too. 0N/A * This routine just fills in the curiously ordered lists. 0N/A * This will be repeated at the beginning of each pass. 0N/A /* First copy the workspace pointers as-is */ 0N/A /* In the second list, put the last four row groups in swapped order */ 0N/A /* The wraparound pointers at top and bottom will be filled later 0N/A * (see set_wraparound_pointers, below). Initially we want the "above" 0N/A * pointers to duplicate the first actual data line. This only needs 0N/A * to happen in xbuffer[0]. 0N/A/* Set up the "wraparound" pointers at top and bottom of the pointer lists. 0N/A * This changes the pointer list state from top-of-image to the normal state. 0N/A/* Change the pointer lists to duplicate the last sample row at the bottom 0N/A * of the image. whichptr indicates which xbuffer holds the final iMCU row. 0N/A * Also sets rowgroups_avail to indicate number of nondummy row groups in row. 0N/A /* Count sample rows in one iMCU row and in one row group */ 0N/A /* Count nondummy sample rows remaining for this component */ 0N/A /* Count nondummy row groups. Should get same answer for each component, 0N/A * so we need only do it once. 0N/A /* Duplicate the last real sample row rgroup*2 times; this pads out the 0N/A * last partial rowgroup and ensures at least one full rowgroup of context. 0N/A * Initialize for a processing pass. 0N/A /* Simple case with no context needed */ 0N/A /* For last pass of 2-pass quantization, just crank the postprocessor */ 0N/A * Process some data. 0N/A * This handles the simple case where no context is required. 0N/A /* Read input data if we haven't filled the main buffer yet */ 0N/A return;
/* suspension forced, can do nothing more */ 0N/A /* There are always min_DCT_scaled_size row groups in an iMCU row. */ 0N/A /* Note: at the bottom of the image, we may pass extra garbage row groups 0N/A * to the postprocessor. The postprocessor has to check for bottom 0N/A * of image anyway (at row resolution), so no point in us doing it too. 0N/A /* Feed the postprocessor */ 0N/A /* Has postprocessor consumed all the data yet? If so, mark buffer empty */ 0N/A * Process some data. 0N/A * This handles the case where context rows must be provided. 0N/A /* Read input data if we haven't filled the _main buffer yet */ 0N/A return;
/* suspension forced, can do nothing more */ 0N/A /* Postprocessor typically will not swallow all the input data it is handed 0N/A * in one call (due to filling the output buffer first). Must be prepared 0N/A * to exit and restart. This switch lets us keep track of how far we got. 0N/A * Note that each case falls through to the next on successful completion. 0N/A /* Call postprocessor using previously set pointers for postponed row */ 0N/A return;
/* Need to suspend */ 0N/A return;
/* Postprocessor exactly filled output buf */ 0N/A /* Prepare to process first M-1 row groups of this iMCU row */ 0N/A /* Check for bottom of image: if so, tweak pointers to "duplicate" 0N/A * the last sample row, and adjust rowgroups_avail to ignore padding rows. 0N/A /* Call postprocessor using previously set pointers */ 0N/A return;
/* Need to suspend */ 0N/A /* After the first iMCU, change wraparound pointers to normal state */ 0N/A /* Prepare to load new iMCU row using other xbuffer list */ 0N/A /* Still need to process last row group of this iMCU row, */ 0N/A /* which is saved at index M+1 of the other xbuffer */ 0N/A * Process some data. 0N/A * Final pass of two-pass quantization: just call the postprocessor. 0N/A * Source data will be the postprocessor controller's internal buffer. 0N/A#
endif /* QUANT_2PASS_SUPPORTED */ 0N/A * Initialize main buffer controller. 0N/A /* Allocate the workspace. 0N/A * ngroups is the number of row groups we need.