line_block_ifc.h

JPEG2000 EBCOT算法源码

       to coding algorithms which have rate-distortion optimization
       capabilities.  The relevant weighting factors (if any) for WMSE
       calculations must currently be supplied via command line arguments
       to the `filter_info__initialize' function.  The WMSE value is expressed
       within a normalized framework in which the original image samples are
       understood to have been scaled down to a nominal range of exactly 1.0
       (i.e. from -0.5 to 0.5).  This helps to reduce the sensitivity of
       algorithms which work with WMSE figures to the bitdepth of the actual
       image samples.
           `extra_lsbs' is used to return the zero-based bit-position, E, of
       the least significant bit in the quantizer symbol indices pushed to
       the encoder and pulled out of the decoder.  As such, it plays an
       extremely important role in correctly interpreting and coding these
       indices.  In a conventional quantizer, one would expect the least
       significant bit to be at bit-position 0.  One of the most important
       innovations in subband quantization and coding techniques, however,
       involves (at least conceptually) a bank of quantizers whose intervals
       (or Voronoi regions) are embedded within one another.  In the simplest
       case, these quantizers correspond to the bit-planes of some finely
       quantized symbol indices.  If we were to devote all bits in the 16-bit
       words passed between the quantization and coding stages to simply
       representing the quantized symbol indices, then we would prevent the
       encoder from recovering accurate information concerning the distortion
       associated with particular quantizers in the embedding.  We would also
       be preventing the decoder from signalling vital information concerning
       the number of bit-planes which were actually decoded to the dequantizer.
           To prevent these difficulties, the quantizer is allowed to pass
       extra information to the encoder via the E least significant bits
       of the magnitude portion of the 16-bit words which are passed across
       the encoder's push interface functions.  Similarly, the decoder can
       signal extra information to the dequantizer via the E
       least significant bits returned via its pull interface functions.  The
       actual quantization step size corresponds to a change of 2^E in the
       magnitude word pushed into or pulled out of the coding stage.  For
       more information on how the remaining E bits are used, consult the
       comments appearing with the `encoder__push_line' and
       `decoder__pull_line' functions.
           It is important to point out here that E is selected to ensure that
       the nominal dynamic range of the integers output by the quantizer
       (including these E bits) will be greater than 2^(R-1) and no larger
       than 2^R where R is the STD_NOMINAL_RANGE_BITS value.  In order to
       guarantee that E >= 1, it is clear that the magnitudes of the
       quantization indices must have a nominal maximum of 2^(R-2), which
       limits the smallest step size which can be used in any given subband.
       If a large number of resolution levels is used and the base step size
       is very small, this might not be adequate to support the step sizes
       computed for very low frequency subbands, using the algorithm described
       above.  To avoid this difficulty, the `filter_info' object automatically
       adjusts the step sizes for these subbands so as to ensure that E >= 1
       during compression (i.e. when FILTER_INFO__SYNTHESIS is not included in
       the `flags' argument supplied to `filter_info__initialize').  During
       decompression, the object uses the `max_bitplanes' argument supplied
       to `filter_info__initialize' to compute the step sizes which were used
       during compression and then converts these directly into step sizes
       and E values for the decompressor, without any adjustment to ensure
       that E is positive.  Consequently, if the implementation precision
       associated with the decompressor is smaller than that associated with
       the compressor, E can be less than 1 and even negative during
       decompression.  In response to this a decoder may choose to issue an
       error message and terminate.  Alternatively, a scalable decoder may
       choose to discard a suitable number of bit-planes from the high
       precision input representation and thereby ensure compatibility
       across different implementation precisions. */

typedef void (*filter_info__terminate__func)
  (filter_info_ref self);
    /* This prototype defines the form of the `terminate' interface function
       associated with the `filter_info' object, whose definition appears
       below.  The function will be called once the compression or
       decompression task is complete.  It should deallocate any memory which
       was allocated, including the memory allocated for the structure
       pointed to by `self'.
           Note that the function may also be called after the object is
       first created, but before the `initialize' function is called.
       Implementors should be aware of this and be careful to avoid attempting
       to deallocate any memory which has not yet been allocated. */

typedef
  struct filter_info_obj {
    filter_info__initialize__func initialize;
    filter_info__print_usage__func print_usage;
    filter_info__get_taps__func get_taps;
    filter_info__get_quant_info__func get_quant_info;
    filter_info__terminate__func terminate;
  } filter_info_obj;

  /* This structure defines all externally visible aspects of the
     `filter_info' object.  In practice, when the object is created, the
     relevant implementation will create a larger structure, containing
     this structure as its first entry and including all relevant fields
     required to maintain state information.  The allocation of the
     structure and any auxiliary storage should be completed in the
     `filter_info__initialize' call.  As mentioned in the introductory
     comments for this file, the external view of any given object consists
     only in a set of function pointers which define the interface to be
     used by all relevant parties.  The function pointers must be set to
     the addresses of the relevant functions when the structure is first
     created.
         The `filter_info' object manages information about the wavelet
     transform filters as well as associated information relevant to the
     way in which the resulting subband sample values are to be quantized.
     Quantization and filtering are intimately connected operations,
     particularly when fixed-point implementations are required, so this
     object is in the best position to jointly optimize filter tap values
     and quantization parameters for the best result. */


/* ========================================================================= */
/* --------------- Interface Definitions for the Compressor ---------------- */
/* ========================================================================= */

typedef struct analysis_obj *analysis_ref;
typedef struct quantizer_obj *quantizer_ref;
typedef struct encoder_obj *encoder_ref;
typedef struct bitstream_sink_obj *bitstream_sink_ref;


/*****************************************************************************/
/*                               analysis_obj                                */
/*****************************************************************************/

typedef void (*analysis__initialize__func)
  (analysis_ref self, int decomposition, int levels, int components,
   int component_rows[], int component_cols[], filter_info_ref info,
   quantizer_ref quantizer, int argc, char *argv[]);
    /* This prototype defines the form of the `initialize' interface function
       associated with the `analysis' object, whose definition appears below.
       The arguments have the following interpretations:
           `self' is a reference (pointer) to the relevant `analysis'
       object (structure), so that private state information can be accessed.
           `decomposition' may be one of DECOMPOSITION__MALLAT or
       DECOMPOSITION__SPACL, but only the former must be supported by
       every implementation.
           `levels' identifies the number of levels of wavelet decomposition.
       A value of 0 means that no wavelet transform should be applied at all.
           `components' identifies the number of components (typically
       colour components) for which a separate Wavelet decomposition with the
       indicated number of levels must be implemented.
           `component_rows' and `component_cols' point to arrays, each of
       which has one entry per component, to identify the height and width
       of the component in the image domain.
           `info' provides a reference to the `filter_info' object whose
       `get_taps' interface function should be used to retrieve the transform
       tap values to use in generating subband sample values.  For floating
       point implementations, no additional normalization of any form should
       be applied to these tap values.  For fixed point implementations,
       however, the analysis stage is responsible for incorporating the
       discrepancy between the exact step sizes and power-of-two
       approximations, as explained in the comments appearing with the
       `filter_info__get_quant_info' interface function.  The `info' object
       must be properly initialized (via a call to its `initialize' member
       function) before being passed into this function.
           `quantizer' provides a reference to the quantizer object into
       which subband sample values should be pushed as soon as they become
       available.
           `argc' and `argv' play the same role as the the arguments passed
       to the `main' function of any "C" program.  They are provided so that
       the initialization function can look for additional special switches
       which customize its behaviour.  For example, a block-based implement
       of the wavelet analysis operation might look for special arguments to
       determine the block size which is to be used.  If special switches are
       used here they should, as a matter of convention, have the prefix,
       "-X", which identifies them as being related to the transform (xform).
       Moreover, the relevant entries in the `argv' array (including those
       representing argument parameters) should be reset to point to an
       empty character string, i.e. ""; this ensures that command-line typos
       can efficiently be caught on behalf of the user. */

typedef void (*analysis__print_usage__func)
  (analysis_ref self, FILE *dest);
    /* This prototype defines the form of the `print_usage' interface function
       associated with the `analysis' object, whose definition appears
       below.  If one or more special command-line arguments are recognized
       by the `analysis__initialize' function, this function
       is responsible for printing a banner line introducing the object,
       which should be followed by a brief description of the command-line
       arguments which are accepted.  The usage text should be sent to the
       file stream identified by `dest'. */

typedef void (*analysis__push_line__func)
  (analysis_ref self, ifc_int *line_buf, int component_idx);
    /* This prototype defines the form of the `push_line' interface function
       associated with the `analysis' object, whose definition appears below.
       The function should be called again and again to push each successive
       line (or row) of the image into the wavelet analysis engine.  The
       function returns once all new subband data which can be generated from
       the new line has been produced and pushed into the quantizer.
       The arguments have the following interpretations:
           `self' is a reference (pointer) to the relevant `analysis'
       object (structure), so that private state information can be accessed.
           `line_buf' is a pointer to an array of 16- or 32-bit integers,
       depending upon the value of the IMPLEMENTATION_PRECISION macro, which
       contain a two's-complement representation of the image sample values
       on the next line of the image.  The analysis engine will normally need
       to buffer up a number of lines internally, to which end it ought to
       copy the contents of this line buffer into suitable internal storage.
       Although copy-free implementations were considered in defining these
       interfaces, we decided that this would needlessly complicate their use
       for the purposes of testing and verifying different compression systems.
       The nominal dynamic range of the sample values in each entry of the
       line buffer must be 2^R, where R is the STD_NOMINAL_RANGE_BITS value.
       Also, the image sample values are assumed to have a symmetric, signed
       representation so that the values lie in the range
       -2^(R-1) to +2^(R-1).