ebcot_decoder.h

来自「JPEG2000 EBCOT算法源码」· C头文件 代码 · 共 689 行 · 第 1/3 页

    code_subblock_ptr first_subblock, last_subblock;
    ifc_int bit_idx;
    std_short *block_update;
    quad_siblings_ptr first_quad, last_quad;
    std_short *context_buffer;
    ifc_int *sample_buffer;
    arith_state coder_state;
    std_byte *zc_lut;
    std_short context_mask;
    context_state contexts[TOTAL_CONTEXTS];
    long int cpu_time;
  } 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_dim' identifies the maximum dimension of each block.  All blocks
     should have `max_dim' rows and `max_dim' columns, except near image
     boundaries.
         `max_sub_dim' identifies the maximum size of each sub-block.  All
     sub-blocks will have `max_sub_dim' rows and `max_sub_dim' columns,
     escept those near block boundaries, which might have smaller dimensions.
         `row_gap' holds the separation between successive rows in the context
     and sample buffers.  It must be large enough to allow legal accesses
     into the context words immediately before and after each row, but not
     to guarantee that these out-of-bound values can be reliably recovered.
     In practice, then, `row_gap' must be at least as large as `max_dim'+1
     and the context array must be allocated in such a way as to allow some
     negative accesses (see `context_buffer' description).
         `first_subblock' and `last_subblock' point to the first and last
     entries in an array which holds all sub-blocks which might be required
     to cover the code block. If the maximum block dimensions are 64x64, for
     example, and the maximum sub-block dimensions are 16x16, this array will
     hold 16 entries, regardless of the size of the actual code block (may be
     smaller near image boundaries).
         `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.
         `block_update' points to a value into which the constant,
     QUAD_PARENT_SIGNIFICANT should be OR'd in the bit-plane at which the
     entire block is first found to be significant.  Exactly as described
     for the `node_update' field in `quad_siblings', this field points either
     to the first entry of a `quad_siblings' structure or a `code_subblock'
     structure, depending upon whether or not there are any further levels of
     quad-tree decomposition in the sub-block significance code.
         `first_quad' and `last_quad' point to the first and last entries of an
     array of `quad_siblings' structures which represents a flat organization
     of the nodes in the partial quad-tree associated with the subblocks.
     The first entry contains the four (may be less) siblings which are
     descended from the root of the quad-tree.  The fields hold NULL if there
     is no quad-tree.
         `context_buffer' points to a common context buffer which is used
     for all blocks.  It holds `row_gap'*(`max_dim'+2)+1 entries, but the
     pointer starts `row_gap'+1 entries into the array, so that the buffer
     can legally be addressed with indices from -(`row_gap'+1) to
     `max_dim'*`row_gap'-1.
         `sample_buffer' points to the buffer which holds the samples being
     decoded.  Rows of sample values are separated by `row_gap', which is
     larger than `max_dim' so the buffer must actually measure
     `row_gap'*(`max_dim'-1) + `max_dim' in size.  In some cases, we may
     be able to use a common sample buffer, while in others this field might
     be set to point to one of a number of different buffers which are
     separately maintained, say, by the line buffering mechanism.  The buffer
     must be initialized to all zeros before the decoding process begins.
         `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.
         `cpu_time' accumulates the CPU time associated with all block
     coding operations.  If CPU time is not required, it should hold a
     negative value. */

/*****************************************************************************/
/*                            block_coding_pass_func                         */
/*****************************************************************************/

typedef void (*block_coding_pass_func)(block_master_ptr master);
  /* This prototype defines the form of the lowest level functions in the
     block coding algorithm.  It uses the supplied `master' object to determine
     the subblocks with the code-block which must be decoded, as well as the
     size and location of each subblock and all parameters relevant to the
     current decoding pass. */

/*****************************************************************************/
/*                                  pass_info                                */
/*****************************************************************************/

typedef
  struct pass_info {
    std_ushort layer_idx;
    std_ushort num_bytes;
  } pass_info, *pass_info_ptr;

  /* This structure provides a facility for remembering the number of
     new block coding passes and the number of new code bytes which are
     required to represent those passes, for each layer in the bit-stream.
     Since the number of coding passes in a given bitstream layer can easily
     be zero, it is best to maintain an array with one entry for each
     potential coding pass, rather than each bit-stream layer, as explained in
     the comments appearing with the `block_info' structure defined below.
         The `layer_idx' field identifies the index of the bit-stream layer
     in which the relevant coding pass appears.
         The `num_bytes' field holds the number of bytes used to represent
     this and any other coding passes for the same block within the bit-stream
     layer.  The field holds a non-zero value only for the first coding
     pass for the block which is included in the bit-stream layer, in case
     there are more.
         The structure is not strictly required for a compliant decoder, but
     it simplifies the testing of the PROFILE__SNR_PARSABLE bit-stream
     profile, by allowing easy emulation of the behaviour of a bit-stream
     parser. */

/*****************************************************************************/
/*                                  block_info                               */
/*****************************************************************************/

typedef
  struct block_info {
    int top_row, left_col, rows, cols;
    int unpulled_blocks;
    ifc_int *pull_block_buffer;
    heap_unit_ptr first_unit;
    int max_passes, num_passes, new_passes;
    pass_info_ptr passes;
    int total_bytes;
    int insignificant_msbs;
  } block_info, *block_info_ptr;

  /* This structure maintains summary information for each coded block.
     An array of these structures is managed from the `band_info' structure,
     with one entry for each block in the subband.  In our current
     implementation the information in these structures is filled out
     based upon the bit-stream which is read in its entirety when the
     decoder object is initialized.
         `top_row', `left_col', `rows' and `cols' hold the block dimensions
     and the indices of the first row and column in the block.  Indices are
     zero based and relate to the subband sampling grid, rather than the image
     sampling grid.
         `unpulled_blocks' and `pull_block_buffer' are used only by the
     `pull_block' interface function.  The `unpulled_blocks' field identifies
     the number of blocks which have not yet been pulled out of the
     `pull_block_buffer' buffer.  The `pull_block_buffer' points to a sample
     buffer array which is used to store the decoded code block until all
     blocks have been pulled out of it.  The sample buffer must conform to the
     requirements of the `sample_buffer' array described under the definition
     of the `block_master' structure.  These sample buffers are allocated
     and recycled via the main decoder object's `sample_buffer_heap_mgr'
     object.
         `first_unit' points to the first `heap_unit' which contains code
     words for the block.
         `max_passes' identifies the maximum number of coding passes for which
     information could be available in the current block.  It is determined
     ahead of time when the `passes' array must be allocated, before any
     information has actually been retrieved from the bit-stream.
         `num_passes' identifies the total number of coding passes for which
     information is actually available in the current block.
         `new_passes' is used to temporarily store the number of new passes
     which are to be added in a given bitstream layer, until all information
     for those passes has become available.
         `passes' points to an array with `max_passes' entries.  Strictly
     speaking, the array is not required to implement a compliant decoder,
     but the provision of a full array of entries facilitates implementation
     and testing of performance with the PROFILE__SNR_PARSABLE bit-stream
     provile flag.  Each entry in this array identifies the bit-stream layer
     within which the relevant coding pass first appears, as well as the
     number of bytes consumed by the current block within that bit-stream
     layer.  With the aid of this information, it is not difficult to
     accurately "parse out" information which exceeds some overall constraint
     on the final bit-rate, without having to actually implement a parser.
     In practice, we do not actually allocate a separate `passes' array
     for each code block.  Instead, we allocate a single array which holds
     the concatenated `passes' arrays for all code blocks in the relevant
     subband.  The first code block's `passes' field points to the head of
     this allocated array.
         `total_bytes' holds the total number of code bytes which are required
     to decode all symbols in the `num_passes' coding passes for the
     block.
         `insignificant_msbs' indicates the number of bit-planes, starting from
     the most significant magnitude bit of the IMPLEMENTATION_PRECISION-bit
     sign-magnitude words, for which all samples in the block were found to
     have zero magnitude. */

/* ========================================================================= */
/* ----------------------------- Line Buffering ---------------------------- */
/* ========================================================================= */

/*****************************************************************************/
/*                               line_buffering                              */
/*****************************************************************************/

typedef
  struct line_buffering {
    int num_lines;
    block_info_ptr info;
    ifc_int **buffers;
  } line_buffering, *line_buffering_ptr;

  /* This structure manages buffering of a row of blocks when data is
     requested by the quantizer in lines rather than blocks.
         `num_lines' holds the number of lines which have been requested
     so far.  Once this reaches the height of a block, the next request for
     a line will force the decoding of a new row of blocks and the `num_lines'
     counter will be reset.
         `info' points to the `block_info' entry for the first block in
     the row of blocks from which lines are being requested.
         `buffers' points to a row of block buffers.  Each block buffer
     conforms to the requirements of the `sample_buffer' array described
     under the definition of the `block_master' structure.  The buffers
     are only allocated in the event that the `pull_line' interface
     function is used. */

/* ========================================================================= */
/* ---------------------------- Subband Structure -------------------------- */
/* ========================================================================= */

/*****************************************************************************/
/*                                  band_info                                */
/*****************************************************************************/

typedef
  struct band_info {
    int component_idx, level_idx, band_idx;
    int band_rows, band_cols;
    int blocks_high, blocks_wide, band_blocks;