ebcot_decoder.h

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

    block_info_ptr blocks;
    std_byte *zc_lut;
    float step_wmse;
    int extra_lsbs;
    line_buffering lines;
    int pull_block_rows;
    int pull_block_cols;
    block_coding_pass_func pass_funcs[PASSES_PER_BITPLANE];
    std_short pass_masks[PASSES_PER_BITPLANE];
    struct tag_tree_node *inclusion_tree;
    struct tag_tree_node *insignificant_msbs_tree;
    int byte_count_bits;
  } band_info, *band_info_ptr;

  /* This structure describes a single subband within the wavelet
     decomposition.
         `component_idx', `level_idx' and `band_idx' hold the component,
     resolution level and subband indices, which are used to address the
     subband.  They are saved here for convenience.
         `band_rows' and `band_cols' hold the dimensions of the subband.
         `blocks_high' and `blocks_wide' hold the number of blocks required
     to span the height and width of the subband, respectively, while
     `band_blocks' simply holds the product of these two numbers.
         `blocks' points to an array with `band_blocks' entries.  Each entry
     stores code words and summary information for the relevant code block.
         `zc_lut' points to the lookup table to be used in translating
     neighbourhood significance information into a coding context for
     decoding whether a zero sample becomes non-zero or not in a particular
     pass; this is called zero-coding.
         `step_wmse' and `extra_bits' are the values recovered from the
     `filter_info' object upon initialization.
         `lines' holds the state information for the line buffering mechanism
     which is activated by calls to the decoder object's `pull_line'
     interface.
         `pull_block_rows' and `pull_block_cols' are used only with the
     `pull_line' interface function.  They record the block size of the
     first block which is requested from the subband.  Apart from boundary
     blocks, all blocks are required to have this same size, which simplifies
     the task of buffering blocks of subband coefficients into code blocks
     when the requested block size is different from the code block size.
         `pass_funcs' holds pointers to the decoding functions to be used
     for each block coding pass in any given bit-plane.
         `pass_masks' array holds the context mask values to be set into the
     `master' structure before passing it into the relevant coding pass.
         `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 bit-stream.  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
     `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_bitstream_layer' function in "ebcot_receive_bits.c".
         `byte_count_bits' holds the current number of bits which is being
     used to signal the number of bytes being sent for a single block coding
     pass in the current bit-stream layer.  The number of bits involved in
     signalling the byte count for multiple coding passes of any given block
     is obtained by adding ceil(log_2(num passes)) to the basic
     `byte_count_bits' value.  The value may be incremented at the beginning
     of each bit-stream layer in which one or more coding passes are added
     for at least one code block, but the value never decreases.  It starts
     out at 3. */

/*****************************************************************************/
/*                                 level_info                                */
/*****************************************************************************/

typedef
  struct level_info {
    int component_idx, level_idx;
    int min_band;
    int max_band;
    band_info bands[4];
    int bitstream_layers;
    std_short *layer_tag_bytes;
  } level_info, *level_info_ptr;

  /* This structure describes a single resolution level.  The `component_info'
     structure manages an array of these structures, with one entry for each
     resolution level and a final entry which represents the image.
         `component_idx' and `level_idx' hold the indices of the relevant
     component and resolution level.  Although not stricly necessary, it is
     handy to keep this information around here.
         `min_band' and `max_band' hold the minimum and maximum indices of
     the subbands which can be accessed within the resolution level.  Most
     levels will have `min_band'=1 and `max_band'=3, but the lowest resolution
     level will have `min_band'=0 (DC band) and the special `level_info'
     structure which represents the original image will have `min_band'
     and `max_band' both equal to 0 if and only if there is no wavelet
     decomposition; if there is a wavelet decomposition, the `min_band'
     value will be larger than `max_band'.
         `bands' holds information for each potential subband in the
     resolution level.  The array should be indexed by the `band_idx' argument
     supplied to the encoder object's `pull_line' or `pull_block' interface
     function.
         `layer_tag_bytes' points to an array with one entry for each
     potential bit-stream layer (the number of these is identified within
     the `the_decoder_obj' object itself), identifying the number of tag
     bytes required to represent tag information for that bit-stream layer.
     The information in this array is not strictly required for a compliant
     decoder, but it allows the PROFILE__SNR_PARSABLE bit-stream profile
     option to be tested properly without implementing a separate bit-stream
     parser.
         `bitstream_layers' identifies the actual number of bitstream layers
     which were recovered from the bit-stream for this resolution level. */

/*****************************************************************************/
/*                               component_info                              */
/*****************************************************************************/

typedef
  struct component_info {
    int component_idx;
    level_info_ptr levels;
  } component_info, *component_info_ptr;

  /* This structure encapsulates all state information for a given component.
         `component_idx' identifies the zero-based index of the relevant
     image component (components are usually associated with colour, but
     need not be).
         `levels' points to an array with `num_levels'+1 entries, as explained
     in the comments appearing with the definition of the `level_info'
     structure, where `num_levels' is the number of resolution levels for
     the Wavelet decomposition and is found in the `the_decoder' structure
     which manages the array of `component_info' structures.  All components
     have exactly the same number of resolution levels in their
     decomposition.  This array should be indexed by the `level_idx' argument
     supplied to the decoder object's `pull_line' or `pull_block' interface
     function. */

/* ========================================================================= */
/* ----------------------------- Decoder Object ---------------------------- */
/* ========================================================================= */

/*****************************************************************************/
/*                                 the_decoder                               */
/*****************************************************************************/

typedef
  struct the_decoder {
    decoder_obj base;
    int profile;
    int num_levels;
    int max_levels;
    int num_components;
    int max_components;
    component_info_ptr components;
    block_master master;
    int max_block_height;
    int actual_bytes;
    int extra_header_bytes;
    int max_bytes;
    bitstream_source_ref input;
    int bitstream_layers;
    codeword_heap_ref code_heap_mgr;
    sample_buffer_heap_ref sample_buffer_heap_mgr;
    ifc_int **tree_to_block_map;
  } the_decoder_obj, *the_decoder_ref;

  /* This structure represents the decoder object itself.  The additional
     fields have the following interpretations:
         `num_levels' holds the number of resolution levels for which
     information may be available in the bit-stream.  This is the maximum
     number of levels in the inverse wavelet transform.  If zero, there is
     no wavelet transform.
         `max_levels', on the other hand, is the maximum number of levels
     for which bit-stream information should be decoded.  Subband samples
     from higher resolution levels should be set to zero by the decoder.
         `num_components' holds the number of image components for which
     information may be available in the bit-stream.
         `max_components', on the other hand, is the maximum number of
     image components for which bit-stream information should be decoded.
     Subband samples from later components should be set to zero by the
     decoder.
         `components' points to an array with `num_components' entries.  The
     state information for any given component is recovered by dereferencing
     the relevant entry and all subordinate structures.  The array should be
     indexed by the `component_idx' argument supplied to the decoder object's
     `pull_line', `pull_block' or `pull_tree' function.
         `master' is a common structure which manages the decoding of
     any given block of subband samples.  The block parameters, common
     storage and a variety of intermediate results are maintained within this
     structure.
         `max_block_height' identifies a limit on the maximum height of any
     code block.
         `actual_bytes' holds the actual number of bytes which are decoded
     after any parsing operations for SNR- or RESOLUTION-PARSABLE profile
     modes.
         `max_bytes' keeps track of the maximum number of bytes which can
     be legally retained after parsing the bit-stream for SNR- or RESOLUTION-
     PARSABLE profile modes, including all relevant tag information; this may
     be smaller than the number of bytes which is available from the
     bit-stream.
         `extra_header_bytes' holds the number of additional header bytes
     which the decoder reads from the bit-stream.  The `max_bytes' and
     `actual_bytes' values both exclude this number, but it must be added
     back in when the `decoder__terminate' function returns the actual
     number of bytes in the bit-stream which it read or parsed.
         `input' holds a reference to the bit-stream source object from which
     the contents of the bit-stream should be read.
         `bitstream_layers' holds the number of layers into which the
     information in the bit-stream has been divided, for each resolution
     level.  For profiles which need not support PROFILE__RESOLUTION_PARSABLE
     or PROFILE__RESOLUTION_PROGRESSIVE, the number of bit-stream layers
     will be exactly 1.
         `code_heap_mgr' references an object which manages the dynamic memory
     allocation for storage of code words.
         `sample_buffer_heap_mgr' references an object which manages the
     dynamic allocation of sample buffers.
         `tree_to_block_map' holds either NULL or a pointer to an array which
     is large enough to hold 2^L pointers to row buffers.  It is created and
     used only by the `decoder__pull_tree' interface function, in order to
     map trees into blocks and retrieve them via the `decoder__pull_block'
     interface function instead. */


/* ========================================================================= */
/* --------------------------- External Functions -------------------------- */
/* ========================================================================= */

extern void
  ebcot_set_pass_funcs_and_masks(band_info_ptr band, int band_idx);

#endif /* EBCOT_DECODER_H */