ebcot_decoder.h

JPEG2000实现的源码

         `error_resilient_termination' indicates whether or not the encoder
     used the predictable error resilient termination policy.  The decoder
     is free to ignore this information if error resilient behaviour is
     not requested.
         `min_erkeep_bits' is zero unless the code stream contains embedded
     error resilience information in some form, i.e. either `segmark' or
     `error_resilient_termination' or both must be true (non-zero).  The
     field is also zero unless the user explicitly requests error resilient
     behaviour at the decoder.  Errors are detected when inspecting the
     segmentation marker and/or termination properties at the end of any
     relevant coding pass.  When an error is detected the relevant coding
     pass is discarded; however, the error may have actually been introduced
     in a previous coding pass where it went undetected because there was
     insufficient error detection code space at that point.  To deal with
     this possibility, whenever error resilience information is verified
     at the end of some coding pass, the number of bits of effective error
     detection code space is stored in the `incremental_er_bits' array for
     that coding pass.  If an error does occur, the decoder discards all
     prior coding passes for which the cumulative number of verified error
     resilience bits is less than the `min_erkeep_bits' value.  Since the
     `min_erkeep_bits' value is a decoder-only parameter, this mechanism
     allows the client to determine how conservative the error resilience
     policy should be.  Larger values for `min_erkeep_bits' lead to increased
     robustness to errors, but generally discard more valid bits in the event
     that an error is detected. */

/*****************************************************************************/
/*                            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. */

/*****************************************************************************/
/*                              ebcot_pass_info                              */
/*****************************************************************************/

typedef
  struct ebcot_pass_info {
    std_ushort layer_idx;
    std_ushort layer_bytes;
    std_short terminated;
    std_ushort special_length;
  } ebcot_pass_info, *ebcot_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 quality layer in the
     codestream.  Since the number of coding passes in a given quality layer
     can easily be zero, it is best to maintain an array with one entry for
     each potential coding pass, rather than each layer, as explained in
     the comments appearing with the `ebcot_block_info' structure defined
     below.
         The `layer_idx' field identifies the index of the quality layer
     in which the relevant coding pass appears.
         The `layer_bytes' field holds the number of bytes used to represent
     this and any other coding passes for the same block within the
     layer.  The field holds a non-zero value only for the first coding
     pass for the block which is included in the same layer, in case
     there are more.
         The `terminated' flag is true (non-zero) if the arithmetic codeword
     segment associated with this coding pass is terminated at the end of
     the coding pass.
         The `special_length' field has a different interpretation when the
     contents of this structure are first filled out in "ebcot_receive_bits.c"
     than that which it assumes later after further processing prior to the
     block decoding operation.  When the bit-stream is initially parsed in
     "ebcot_receive_bits.c", the `special_length' value is set only for those
     coding passes marked as `terminated'.  For these coding passes the field
     identifies the number of bytes at which the coding pass is terminated,
     relative to the start of the relevant layer.  Later, the array of coding
     pass information structures for each code-block is processed to modify
     the interpretation of the `special_length' field to mean the total
     number of bytes from the start of the block bit-stream until the
     termination point for the arithmetic code-word segment used for the
     current coding pass (and any future coding passes up to the next
     termination point).  The former, transient interpretation, is for
     implementation convenience only. */

/*****************************************************************************/
/*                              ebcot_block_info                             */
/*****************************************************************************/

typedef
  struct ebcot_block_info {
    int top_row, left_col, rows, cols;
    dst_heap_unit_ptr first_unit;
    int max_passes, num_passes, new_passes;
    ebcot_pass_info_ptr passes;
    int special_lengths_converted;
    int total_bytes;
    int num_signalled_passes, total_signalled_bytes; /* David T ER mod. */
    int insignificant_msbs;
    int byte_count_bits;
    struct ebcot_precinct_info *precinct;
  } ebcot_block_info, *ebcot_block_info_ptr;
  /* This structure maintains summary information for each coded block.
     An array of these structures is managed from the
     `ebcot_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
     relative to the upper left hand sample in the relevant subband tile.
     They are not expressed relative to the absolute canvas coordinate system.
         `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 codestream for the
     relevant tile.
         `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 quality 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 simulated
     parsing of the codestream to a reduced bit-rate.  Each entry in this
     array identifies the quality layer within which the relevant coding
     pass first appears, as well as the number of bytes consumed by the
     current block within that 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 for the purpose of
     deallocation.
         `special_lengths_converted' is a flag indicating whether or not
     the conversion has been made between the two different interpretations
     identified in the definition of the `ebcot_pass_info' structure for
     the `special_length' fields in each element of the `passes' 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.
         `num_signalled_passes' identifies the total number of coding passes
     for which information has been signalled in packet headers.  This might
     be larger than `num_passes' if the code-block is corrupted.
         `total_signalled_bytes' identifies the total number of code-block
     bytes for which information has been signalled in packet headers.  This
     might be larger than `total_bytes' if the code-block is corrupted.
         `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.
         `byte_count_bits' is used by the T2 coding engine to code the
     number of bytes between successive termination and/or truncation points.
     Specifically, `byte_count_bits' holds the number of bytes per coding
     pass which were last used to signal differential code length information.
     To signal a new length quantity, L, corresponding to P new coding passes,
     we required the value of `byte_count_bits', B, to satisfy
     L < 2^(B*floor(log_2(P))).  A comma code is used to increment the
     value of B until this condition is satisfied, after which the value of
     L is signalled using B*floor(log_2(P)) bits.
         `precinct' points to the precinct corresponding to this code block.
     At the point when the block must be decoded, its precinct is examined
     to determine whether or not all recoverable layers (i.e. all recoverable
     packets) have in fact been recovered from the codestream.  If not,
     packets are retrieved from the codestream until we can be sure that
     all recoverable layers have indeed been recovered.  This provides a
     mechanism for incremental consumption of the codestream. */

/*****************************************************************************/
/*                           ebcot_precinct_band_info                        */
/*****************************************************************************/

typedef
  struct ebcot_precinct_band_info {
    int blocks_high, blocks_wide, total_blocks, block_row_gap;
    ebcot_block_info_ptr blocks;
    struct ebcot_band_info *band;
    struct tag_tree_node *inclusion_tree;
    struct tag_tree_node *insignificant_msbs_tree;

    /* SAIC General Decomp. Begin */
    int valid_band;
    /* SAIC General Decomp. End */

  } ebcot_precinct_band_info, *ebcot_precinct_band_info_ptr;
  /* Holds information specific to a given precinct within a subband.
         `blocks_high' and `blocks_wide' hold the number of blocks required
     to span the height and width of the precinct within the relevant subband,
     while `total_blocks' holds the product of these two fields.  The
     `block_row_gap' field identifies the total number of code-blocks between
     consecutive rows of blocks within the `blocks' array.  In practice, this
     is identical to the `blocks_wide' field in the corresponding
     `ebcot_band_info' structure.
         `blocks' points to the first block of the precinct.  It is actually a
     pointer into the `blocks' array managed by the corresponding
     `ebcot_band_info' structure.  Each entry stores code words and summary
     information collected while coding the relevant block.  Note that this
     field may be NULL if the precinct contains no blocks; this can happen.
         `band' points to corresponding `ebcot_band_info' structure.
         `inclusion_tree' and `insignificant_msbs_tree' point to tag-tree
     structures which manage the efficient decoding of tag bits which represent
     two types of information in the packet header.  The `inclusion_tree'
     structure is used to recover information about whether or not any coding
     passes have been included into the bit-stream so far, for each of the
     blocks in the subband.  The `insignificant_msbs_tree' structure is used
     to recover information embodied in the `insignificant_msbs' field of each
     `ebcot_block_info' structure for blocks within the subband.  Beyond this
     brief description, the use of these data structures is best understood
     by reading the comments appearing with the definition of tag trees in
     "ebcot_receive_bits.h" and the implementation of the
     `recover_packet' function in "ebcot_receive_bits.c". 

      SAIC General Decomp. Begin
          `valid_band' indicates which bands in the range [min_band, max_band]
      are valid for a general decomposition.
      SAIC General Decomp. End */

/*****************************************************************************/
/*                             ebcot_precinct_info                           */
/*****************************************************************************/

typedef
  struct ebcot_precinct_info {
    int tnum, component_idx, level_idx, precinct_idx;
    int xref, yref;