ebcot_decoder.h

JPEG2000实现的源码

/*****************************************************************************/
/* Copyright 1998, Hewlett-Packard Company                                   */
/* All rights reserved                                                       */
/* File: "ebcot_encoder.h"                                                   */
/* Description: Principle header file for the EBCOT encoder                  */
/* Author: David Taubman                                                     */
/* Affiliation: Hewlett-Packard and                                          */
/*              The University of New South Wales, Australia                 */
/* Version: VM8.0                                                            */
/* Last Revised: 28 July, 2000                                               */
/*****************************************************************************/

/*****************************************************************************/
/* Modified to combine entropy coders                                        */
/* Copyright 1999 Science Applications International Corporation (SAIC).     */
/* Copyright 1999 University of Arizona, Arizona Board of Regents.           */
/* All Rights Reserved for modified parts.                                   */
/*****************************************************************************/

/*****************************************************************************/
/* Modified to include TCQ                                                   */
/* Copyright 1999 Science Applications International Corporation (SAIC).     */
/* Copyright 1995 University of Arizona, Arizona Board of Regents.           */
/* All Rights Reserved for modified parts.                                   */
/*****************************************************************************/

/*****************************************************************************/
/* Modified by David Taubman to support arbitrary reference points for the   */
/* transform and the various regular partitions, so as to facilitate         */
/* cropping and geometric transformations in the compressed domain and to    */
/* enable full support for CRF's single-sample overlap Wavelet transform,    */
/* as originally documented in Seoul.  Changes are too numerous to flag      */
/* individually within the code.  Changes copyrighted by HP with all rights  */
/* reserved for the modified parts.                                          */
/*****************************************************************************/

/*****************************************************************************/
/* Modified by David Taubman to support interface modifications, arbitrary   */
/* changes in coding parameters from component to component and from tile    */
/* to tile, packet partitions, rich packet sequencing conventions and to     */
/* support the full generality of PART-1 of the JPEG2000                     */
/* standard, and to support most anticipated generality of PART-2.  Changes  */
/* are too numerous to flag individually within the code, which in some      */
/* places has been completely rewritten.  All changes copyrighted by HP with */
/* all rights reserved for the modified parts.                               */
/*****************************************************************************/

/*****************************************************************************/
/* Modified by David Taubman to implement changes in Tokyo between CD and    */
/* FCD for Part-1 of the standard.  Copyrighted by HP with all rights        */
/* reserved for the modified parts.                                          */
/*****************************************************************************/

/*****************************************************************************/
/* Modified for general wavelet decompositions.                              */
/* Copyright 2000 Science Applications International Corporation (SAIC).     */
/* Copyright 1995 University of Arizona, Arizona Board of Regents.           */
/* All Rights Reserved for modified parts.                                   */
/*****************************************************************************/

/*****************************************************************************/
/* Modified by David Taubman to incorporate changes to the POC marker (used  */
/* to be POD).  Changes are quite extensive and not always explicitly        */
/* When flagged, the relevant comment string is "DST POC mod".               */
/* Copyright 2000 The University of New South Wales.                         */
/* All rights reserved for the modified parts.                               */
/*****************************************************************************/

#ifndef EBCOT_DECODER_H
#define EBCOT_DECODER_H
#include <ifc.h>
#include <dst_arith_decoder.h>
#include "ebcot_common.h"
#include "ebcot_constants.h"

/* ========================================================================= */
/* -------------------------- Block Coding Structure ----------------------- */
/* ========================================================================= */

/*****************************************************************************/
/*                                 block_master                              */
/*****************************************************************************/

typedef
  struct block_master {
    int max_height, max_width, height, width;
    int max_stripes, stripes;
    int interleaved_row_gap, sample_row_gap;
    int causal, reset, terminate_each_pass, lazy;
    ifc_int bit_idx;
    ifc_int first_bit_idx;
    int full_effort_msbs;
    ifc_int *interleaved_sample_buffer;
    std_short *interleaved_context_buffer, *context_buffer_handle;
    std_int *speed_up_buffer, *speed_up_handle;
    int speed_up_row_gap;
    dst_arith_state coder_state;
    std_byte *zc_lut;
    dst_context_state contexts[DST_ARITH_MAX_CTXTS*2];
    std_byte **roi_mask;
    int segmark;
    /* Fields for optional error resilient behaviour. */
    int error_resilient_termination;
    int min_erkeep_bits;
    int incremental_er_bits[MAX_PASSES];
  } block_master, *block_master_ptr;
  /* There is only one instance of this structure in the entire system.
     It holds all intermediate information involved in the decoding of a
     single block of samples.  Many of its fields must be initialized
     for each new block.
         `max_height' and `max_width' identify the maximum height and width
     of each code block, whereas `height' and `width' hold the actual height
     and width of the current code-block being processed.
         `max_stripes' holds the maximum number of stripes, each of which
     holds four rows (some of these rows may possibly be missing in the last
     stripe of the code-block), whereas `stripes' holds the actual number of
     vertical stripes in the current code-block.
         `interleaved_row_gap' holds the gap between samples with the same
     position in vertically adjacent stripes within the
     `interleaved_sample_buffer'.
         `sample_row_gap' holds the gap between samples on consecutive
     lines within the sample buffers supplied to the `encode_block'
     function; this is a constant, generally equal to the `max_width' value.
         `causal' is a flag identifying whether or not the context formation
     process should be vertically stripe-causal.
         `reset' is a flag identifying whether or not the probability
     models should be reinitialized at the beginning of each coding pass.
         `terminate_each_pass' is a flag identifying whether or not the
     arithmetic code-word generation process was terminated at the
     end of each coding pass.  Note that this need not necessarily be
     accompanied by model reset.
         `lazy' is a flag identifying whether or not the lazy coding mode
     is to be used, as parametrized by the `full_effort_msbs' field (see
     below).
         `bit_idx' identifies the bit position of the current magnitude bit
     plane.  It is initially set to IMPLEMENTATION_PRECISION-2 (bit position
     indices are zero-based) and then decremented for each successive
     bit-plane.
         `first_bit_idx' holds the value of `bit_idx' in the first bit-plane
     for which any sample was significant.
         `full_effort_msbs' holds the number of most significant bit-planes,
     starting with the first bit-plane in which the relevant code-block is
     first found to be significant, for which arithmetic coding is used in
     all passes.  After this point, only the main coding pass (i.e. that
     in which samples with previously all-zero neighbourhoods are coded)
     receives the full coding effort, and the other passes are performed
     without the aid of arithmetic coding, sending the raw binary symbols
     directly to the bit-stream.  Note that this behaviour occurs only
     when the `elias' flag is turned on.
         `interleaved_sample_buffer' points to the buffer which holds the
     samples to be encoded.  The sample buffer is organized in terms of
     stripes.  Specifically, the stripes appear one after the other, with
     some intervening spacing to avoid access violations at boundaries.
     The four rows of each stripe are interleaved and corresponding samples
     from adjacent stripes are separated by `stripe_gap' entries
     in the array.
         `er_save' should be NULL unless error concealment capabilities
     have been requested, in which case it points to a second sample buffer
     in which we save a copy of the sample values which were decoded up to
     and including the last coding pass at which the set of decoded symbols
     appeared to be uncorrupted.  If we detect corruption at some point then
     we simply revert to this saved set of sample values.  The block
     decoder performs the relevant tests for corruption if and only if the
     `er_save' field is non-NULL.  The buffer must have the same organization
     as the `interleaved_sample_buffer'.
         `interleaved_context_buffer' points to a common context buffer which
     is used for all code-blocks.  It has the same interleaved stripe
     organization as the `interleaved_sample_buffer' array.  There is a single
     16-bit context word for each sample, which is updated only when the
     sample or one of its immediate neighbours becomes significant.  The
     value of `stripe_gap' is chosen to be sufficiently large to
     ensure that accesses of up to eight stripe columns beyond the last
     sample in any stripe will not cause any access violations or overwrite
     real data.  Also, accesses one stripe column to the left and a full
     stripe before the first sample in the code-block or four samples to the
     right and a full stripe after the last sample in the code-block will not
     cause access violations, which means that the base of the allocated
     memory is below the location pointed to by the
     `interleaved_context_buffer' field.  For ease of deallocation, this
     base address is kept in the `context_buffer_handle' field.
         `speed_up_buffer' points to an array of 32-bit words, each of which
     holds significance summary information for 8 consecutive stripe
     columns, used to improve the execution speed of the algorithm.  Use of
     these speed up tricks is an implementation issue and is not required
     for a compliant decoder.  Specifically, only bit positions 8 through
     15 of each word are actually used; all other bits must be 0.  Bit
     position 8 of the first word in the array holds 0 if and only if the
     first stripe column in the code-block is fully populated (i.e. no
     missing rows in the stripe) with all four samples currently insignificant
     and the immediate vertical neighbours (i.e. the neighbour immediately
     above in the previous stripe and immediately below in the following
     stripe) are both currently insignificant.  Bit 9 has the same
     interpretation for the second stripe column in the code-block and so
     forth.  Since each word represents 8 consecutive stripe columns, there
     must be at least `width/8' words per stripe.  In practice, the words
     for consecutive stripes are separated by `speed_up_row_gap' entries
     where this value is sufficiently large to ensure that there are at
     least `max_width'/8 + 1 words per stripe.  The flag bits corresponding
     to stripe columns beyond the right hand boundary of the code-block
     must be set carefully to allow the efficient implementation to work
     correctly.  Specifically, the stripe column immediately following the
     right hand boundary of the block is marked with a 0 bit (i.e.
     insignificant), but the flag bits for following stripe columns are
     set to 1.  This policy ensures that the implementation need not
     explicitly check for violation of the boundary when searching for
     runs of samples with insignificant neighbourhoods.  The
     `speed_up_buffer' array may be addressed with stripe indices ranging
     from -1 to `max_stripes' (i.e. there is an extra stripe row before
     and after the nominal array dimensions).  To allow this, the actual
     base of the allocated memory is referenced by `speed_up_handle' for
     ease of deallocation.
         `coder_state' holds the current state of the arithmetic coder.
         `zc_lut' identifies the zero-coding lookup table to be used in
     selecting coding contexts based upon the significance of the eight
     immediate neighbours.  An appropriate pointer will be inserted here
     for each band.
         `contexts' holds the context state information used by the adaptive
     arithmetic coder.  Its entries are set to some initial state (usually
     equi-probable distributions) before decoding each block.
         `roi_mask' points to an array with `max_height' entries which is used
     to store pointers to the rows of the mask returned by calls to
     `reverse_roi__check_roi'.
         `segmark' indicates whether or not the normalization pass of each
     bit-plane contains a trailing segmentation marker code.  When this
     coding pass does not contain a termination of the MQ codeword, the
     segmentation marker must be read even if the decoder has no desire
     to implement an error detection mechanism.