ebcot_encoder.h

JPEG2000 EBCOT算法源码

    block_info_ptr blocks;
    std_byte *zc_lut;
    heap_unit_ptr heap_head, heap_tail;
    int next_heap_pos;
    float step_wmse;
    int extra_lsbs;
    line_buffering lines;
    int push_block_rows;
    int push_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;
    struct tag_tree_node *inclusion_tree_copy;
    struct tag_tree_node *insignificant_msbs_tree_copy;
    int byte_count_bits, byte_count_bits_copy;
  } 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 collected while coding
     the relevant block.
         `zc_lut' points to the lookup table to be used in translating
     neighbourhood significance information into a coding context for
     coding whether a zero sample becomes non-zero or not in a particular
     pass; this is called zero-coding.
         `heap_head' and `heap_tail' point to the first and last entries in
     the doubly-linked list of heap units which are used to store the
     code words for all sub-blocks in the band.
         `next_heap_pos' holds the position within the `heap_tail' unit of
     the next unused word of storage.  The code words generated by all the
     blocks in a subband are concatenated together, but each block starts
     on a new whole word boundary.
         `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 encoder object's `push_line'
     interface.
         `push_block_rows' and `push_block_cols' are used only with the
     `push_line' interface function.  They record the block size of the
     first block which is pushed in for 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 pushed block size is different from the code block size.
         `pass_funcs' holds pointers to the encoding 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 writing of tag bits to represent
     two types of information in the generated bit-stream.  The
     `inclusion_tree' structure is used to represent 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 represent 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_send_bits.h" and the
     implementation of the `form_bitstream_layer' function in
     "ebcot_send_bits.c".
         `inclusion_tree_copy' and `insignificant_msbs_tree_copy' are provided
     to allow the state of a bit-stream layer generation pass to be saved
     and later recalled.
         `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 used to
     signal the byte count for multiple coding passes is obtained by adding
     ceil(log_2(num_passes)) to the basic `byte_count_bits' value.  The
     `byte_count_bits' value may be incremented at the beginning of each
     bit-stream layer which contains one or more new coding passes for at
     least one block, but it never decreases.  It starts out at 3.
         `byte_count_bits_copy' is provided to allow the state of a bit-stream
     layer generation pass to be saved and later recalled. */

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

typedef
  struct level_info {
    int component_idx, level_idx;
    int min_band;
    int max_band;
    band_info bands[4];
  } 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 `push_line' or `push_block' interface
     function. */

/*****************************************************************************/
/*                               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_encoder' 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 encoder object's `push_line' or `push_block' interface
     function. */

/* ========================================================================= */
/* ---------------------------- Bit-Stream Layers -------------------------- */
/* ========================================================================= */

/*****************************************************************************/
/*                             bitstream_layer_info                          */
/*****************************************************************************/

typedef
  struct bitstream_layer_info {
    int max_cumulative_bytes;
    int actual_cumulative_bytes;
    int optimize;
    std_int rd_threshold;
  } bitstream_layer_info, *bitstream_layer_info_ptr;

  /* This structure keeps track of information involved in the formation of
     bit-stream layers.  A bit-stream layer is composed of a collection of
     coding passes from some or all of the subband code blocks.  The layer
     may be assembled in an optimal way subject to some target bit-rate.
     Alternatively, it may be assembled more rapidly to approximately
     achieve some target bit-rate.  The encoder accepts command line
     argument to identify the number of bit-stream layers and any special
     bit-rates for which a full optimization is requested.  The fields of
     this structure have the following interpretation:
         `max_cumulative_bytes' holds the maximum number of bytes which
     can be consumed by this and any previous bit-stream layers, together.
     This is a hard maximum if `optimize' is non-zero (true); othewise, it
     represents a target bit-rate.
         `actual_cumulative_bytes' identifies the actual number of bytes
     which are consumed by this and any previous bit-stream layers.  It
     is not known until after the bit-stream layer has been formed.
         `rd_threshold' is the rate-distortion threshold associated with
     the bit-stream layer.  The layer includes all coding passes from all
     code blocks, such that the rate-distortion slope associated with that
     coding pass is greater than or equal to this threshold.  The threshold
     is determined iteratively if `optimize' is true, in order to find the
     smallest threshold which is compatible with the `max_cumulative_bytes'
     constraint.  If `optimize' is zero (false), however, the threshold is
     estimated from summary information accumulated during block coding. */

/* ========================================================================= */
/* ----------------------------- Encoder Object ---------------------------- */
/* ========================================================================= */

/*****************************************************************************/
/*                                 the_encoder                               */
/*****************************************************************************/

typedef
  struct the_encoder {
    encoder_obj base;
    int profile;
    int num_levels;
    int num_components;
    component_info_ptr components;
    bitstream_sink_ref output;
    block_master master;
    int max_block_height;
    int bitstream_layers;
    bitstream_layer_info_ptr layer_info;
    codeword_heap_ref code_heap_mgr;
    sample_buffer_heap_ref sample_buffer_heap_mgr;
    ifc_int **tree_to_block_map;
  } the_encoder_obj, *the_encoder_ref;

  /* This structure represents the encoder object itself.  The additional
     fields have the following interpretations:
         `num_levels' holds the number of resolution levels in the wavelet
     transform.  If zero, there is no wavelet transform.
         `num_components' holds the number of components in the image.
     This must be strictly positive.
         `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 encoder object's
     `push_line', `push_block' or `push_tree' function.
         `output' holds a reference to the bit-stream sink object into which
     the final bit-stream should be written.
         `master' is a common structure which manages the encoding 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 number of
     rows which may be included in any code block.
         `bitstream_layers' holds the number of layers into which we will
     divide the information written into the bit-stream 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.
         `layer_info' points to an array with one entry for each bit-stream
     layer, which identifies the target size for that layer and other
     information which is used during bit-stream formation to produce
     bit-stream which have particular properties.  The bit-stream layer
     information need never be included in the bit-stream itself, since the
     decoder need only be aware of the number of layers.
         `code_heap_mgr' references an object which manages the dynamic memory
     allocation for storage of generated 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 `encoder__push_tree' interface function, in order to
     map trees into blocks and pass them across the `encoder__push_block'
     interface function i nstead. */

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

extern void
  ebcot_set_pass_funcs_and_masks(band_info_ptr band, int band_idx);

#endif /* EBCOT_ENCODER_H */