ebcot_decoder.h

JPEG2000实现的源码

     `precincts_high'.  There will often only be one precinct in any given
     resolution level, which is the original form proposed for the EBCOT
     algorithm; multiple precincts can be used to improve parsability and/or
     coherence in the codestream to reduce resource consumption in specific
     applications.
         `precincts' points to an array of `total_precincts'
     `ebcot_precinct_info' structures which manage the state of each precinct.
         `next_precinct_idx' holds the index of the next precinct in this
     resolution level to be included in a spatially oriented precinct
     progression sequence.  It is used only to build these sequences and
     has no interpretation at any other point. */

/*****************************************************************************/
/*                            ebcot_component_info                           */
/*****************************************************************************/

typedef
  struct ebcot_component_info {
    int tnum, component_idx;
    canvas_dims dims;
    int hor_subsampling, vert_subsampling;
    int num_levels;
    int max_levels;
    ebcot_level_info_ptr levels;
    block_master master;
    sample_buffer_heap_ref sample_buffer_heap_mgr;
    int respect_frames;
  } ebcot_component_info, *ebcot_component_info_ptr;
  /* This structure encapsulates all state information for a given image
     component within a particular tile.
         `tnum' and `component_idx' identify the coordinates of the component.
         `dims' holds the dimensions and location of the relevant
     tile-component on the canvas.
         The `hor_subsampling' and `vert_subsampling' fields identify the
     horizontal and vertical sub-sampling factors for this component; these
     may be used to recover the entries in the `dims' structure from those
     in the `referernce_dims' structure within the containing `ebcot_tile'
     structure.
         `num_levels' holds the number of Wavelet decompostion levels, which
     is equal to the number of resolution levels minus 1.
         `max_levels' holds the value of `num_levels' minus the
     `discard_levels' value maintained by the `ebcot_decoder' object.
         `levels' points to an array with `num_levels'+1 entries.  The
     first entry manages the state of the LL band at the base of the
     decomposition.  The n'th entry (n=1,2,...) manages stage for all subbands
     required to recover resolution level n, from the previous resolution.
         `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 on behalf of all code-blocks in the tile-component.
         `sample_buffer_heap_mgr' references an object which manages the
     dynamic allocation of sample buffers.
         `respect_frames' is a flag indicating whether or not code-blocks
     are required to respect frame dimensions.  If so, then the code-block
     dimensions in any given subband will be the lesser of the nominal
     code-block dimensions as maintained by `master->max_block_rows' and
     `master->max_block_cols', the frame dimensions as they appear in the
     relevant subband, and the precinct partition dimensions as they appear
     in the relevant subband.  Otherwise, the code-block dimensions will
     be the lesser of the nominal block dimensions and the precinct partition
     dimensions for the subband. */

/*****************************************************************************/
/*                               ebcot_sequence                              */
/*****************************************************************************/

typedef
  struct ebcot_sequence {
    int layer_idx;
    ebcot_precinct_info_ptr precinct;
  } ebcot_sequence, *ebcot_sequence_ptr;
  /* This structure is used to maintain the identity of a particular
     codestream packet in sequence.  A codestream packet consists of
     a particular quality layer within the region identified by the
     `precinct' pointer; this simply points into the `precincts' array managed
     by the appropriate `ebcot_level_info' structure. */

/*****************************************************************************/
/*                                 ebcot_tile                                */
/*****************************************************************************/

typedef
  struct ebcot_tile {
    int tnum;
    canvas_dims reference_dims;
    int overlapped;
    int constructed;
    int num_components;
    int max_components;
    ebcot_component_info_ptr components;
    int max_levels;
    int num_layers;
    int total_packets;
    int sequenced_packets; /* DST POC mod */
    int available_packets;
    ebcot_sequence_ptr packet_sequence;
    int current_poc_instance; /* DST POC mod */
  } ebcot_tile, *ebcot_tile_ptr;
  /* This structure encapsulates all state information for a single tile.
     All parameters, with the exception of the number of
     image components, may change from tile-to-tile.
         The `tnum' field identifies the coordinate of the tile.
         The `reference_dims' structure describes the location and dimensions
     of the tile on the reference grid.
         The `overlapped' flag holds 1 if any of the tile's image components
     uses tile overlapping.  If true then spatially oriented packet
     progression orders for the tile are not currently well defined.
         The `constructed' flag indicates whether or not the tile's
     resolution levels and all other structures which may be tile-specific
     have been constructed.
         The `num_components' field indicates the number of image components.
     This is the same in every tile, but it is convenient to keep it here.
         The `max_components' field holds a replica of its namesake in the
     `ebcot_decoder' object for convenience when determining what to do
     with packets once they have been parsed from the codestream.
         The `components' array manages the state information for each
     image component within the tile.  We call these tile-components.
         The `max_levels' field holds the maximum number of resolution
     levels in any component within the tile.
         The `num_layers' field holds the number of quality layers for
     the tile; it can vary from tile-to-tile, although this creates some
     interpretation dilemmas.
         The `total_packets' field indicates the total number of packets
     contained in the tile.  This is the sum of the `total_precincts' fields
     from all `ebcot_level_info' structures, all multiplied by the number
     of quality layers.
         The `available_packets' field indicates the total number of
     codestream packets, in sequence, which have been recovered from the
     codestream up to the current point.
         The `sequenced_packets'  array identifies the total number of
     packets for which sequencing information is currently available.  If
     an unsequenced packet is required by the block decoding engine, the
     relevant sequencing information is automatically requested from the
     bit-stream object.
         The `packet_sequence' field points to an array with `total_packets'
     entries, each of which corresponds to a particular packet, in the
     sequence in which packets appear in the codestream.
         The `current_poc_instance' field identifies the instance number of
     the most recent POC marker from which packet sequencing information
     has been deduced.  If an unsequenced packet is requested, the index
     is advanced and the next POC marker is requested and processed; this
     is repeated as often as necessary until the sequence index of the
     next packet can be deduced (a POC marker might fail to augment the
     number of sequenced packets, since all packets within its scope might
     already have been sequenced). */

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

/*****************************************************************************/
/*                               ebcot_decoder                               */
/*****************************************************************************/

typedef
  struct ebcot_decoder {
    decoder_obj base;
    reverse_info_ref info;
    stream_in_ref stream;
    reverse_roi_ref roi;
    int num_components;
    int max_components;
    int discard_levels;
    int num_tiles;
    int current_tile_idx;
    ebcot_tile_ptr tiles;
    int max_component_rows, max_component_cols;
    dst_codeword_heap_ref code_heap_mgr;
    std_int cpu_time;
    int no_speedup;
    int er_confidence;
    int actual_bytes;
  } ebcot_decoder_obj, *ebcot_decoder_ref;
  /* This structure represents the decoder object itself.  The additional
     fields have the following interpretations:
         `stream' holds a reference to the `stream_in' object from which
     packet data and all markers are recovered in an incremental manner.
         `roi' holds a reference to the ROI object which may modify the
     entropy coder's behaviour in particular code-blocks.
         `num_components' holds the actual number of image components in
     the codestream which is being decompressed, while `max_components'
     identifies the maximum number of these components for which we expect
     accesses via the `decoder__pull_line' interface function; at any rate,
     accesses outside these components should consistently return 0's.
         `discard_levels' indicates the number of resolution levels which
     are to be discarded from each tile.  We do not expect requests for
     information via the `decoder__pull_line' interface function for any
     of the discarded lines; nevertheless, if such a request is made, the
     object should consistently return 0's.
         `num_tiles' indicates the total number of tiles which represent
     the image.
         `current_tile_idx' holds the zero-based index of the current tile
     for which information is being retrieved via the `decoder__pull_line'
     interface function.
         `tiles' points to an array with `num_tiles' structures, which manage
     the state and coding parameters of each tile.  Most properties of the
     coder are derived separately from each `ebcot_tile' structure.  Moreover,
     the tile contents and organization are filled out only as needed.
         `code_heap_mgr' references an object which manages the dynamic memory
     allocation for storage of generated code words.
         `cpu_time' accumulates the CPU time associated with all block
     coding operations.  If CPU time is not required, it should hold a
     negative value.
         `no_speedup' is a flag indicating whether or not the default
     speedup mode for the entropy decoder should be turned off -- useful
     for benchmarking and debugging.
         `er_confidence' holds 0 unless error resilient decoding is
     requested, in which case it holds the number of confidence bits
     supplied with the `-Cer' argument.
         `actual_bytes' identifies the total number of bytes retrieved
     from the codestream which were actually used during decompression;
     if not identical to the number of bytes actually retrieved from the
     codestream, this reflects the activities of simulated codestream
     parsing. */


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

extern void
  ebcot_set_pass_funcs(ebcot_band_info_ptr band, block_master_ptr master,
                       int no_speedup); /* DST SU RESTORE */

#endif /* EBCOT_DECODER_H */