line_block_ifc.h

JPEG2000 EBCOT算法源码

    precision must be determined at compile time. */


/* ========================================================================= */
/* -------------------------- Common constants ----------------------------- */
/* ========================================================================= */

#define STD_OVERFLOW_BITS 2
   /* See comments on STD_NOMINAL_RANGE_BITS to understand the role of
      this macro. */

#define STD_NOMINAL_RANGE_BITS (IMPLEMENTATION_PRECISION-STD_OVERFLOW_BITS)
   /* This macro identifies the number of bits which are generally required
      to represent image, subband and quantized sample values which lie within
      the nominal range.  The nominal range for image sample values will
      usually be the bit-depth.  This means that image sample values supplied
      to the `analysis' object and retrieved from the `synthesis' object must
      always have a bit-depth of STD_NOMINAL_RANGE_BITS.  In order to map
      between the actual image sample bit-depth and this nominal value, a
      left or right shift operation will usually be required.  The Wavelet
      transform objects (`analysis' and `synthesis') work to preserve the
      image sample nominal range in all subbands.  The exact interpretation
      of nominal range for subband samples appears in the comments
      accompanying the relevant object definitions below.  It is important
      to understand that some sample values may exceed the nominal dynamic
      range under unusual circumstances.  STD_OVERFLOW_BITS additional bits
      are left at the top of the maximum representable dynamic range to
      guard against overflow when this happens.  STD_NOMINAL_RANGE_BITS
      also affects the interpretation of quantized subband samples, as
      explained in the comments appearing with the definitions of the
      relevant objects, below. */

#define DECOMPOSITION__MALLAT    0 /* Must be supported by all objects. */
#define DECOMPOSITION__SPACL     1 /* Optional decomposition structure. */

#define FILTER_INFO__RADIX_QUANT 1 /* See `filter_info__initialize'. */
#define FILTER_INFO__IDEAL_QUANT 2 /* See `filter_info__initialize'. */

#define FILTER__HIGH   1  /* See `filter_info__get_taps'. */
#define FILTER__VERT   2  /* See `filter_info__get_taps'. */
#define FILTER__SYNTH  4  /* See `filter_info__get_taps'. */

#define LL_BAND 0 /* Index of vertically and horizontally low pass band */
#define HL_BAND 1 /* Index of vertically low and horizontally high pass band */
#define LH_BAND 2 /* Index of vertically high and horizontally low pass band */
#define HH_BAND 3 /* Index of vertically and horizontally high pass band */

#define PROFILE__RANDOM_ACCESS           1
#define PROFILE__SNR_PROGRESSIVE         2
#define PROFILE__SNR_PARSABLE            4
#define PROFILE__RESOLUTION_PROGRESSIVE  8
#define PROFILE__RESOLUTION_PARSABLE    16
#define PROFILE__COMPONENT_PARSABLE     32
  /* The above macros define a set of profile flags which are passed into the
     encoder and decoder during initialization.  Both the coding algorithm
     and the bit-stream organization may be affected by the particular set of
     profile flags which is requested; however, it is most desirable to
     limit the effect of these flags only to the bit-stream organization.
     Any or all of the profile flags may appear in the profile word supplied
     to the encoder.  The flags have the following interpretation:
        RANDOM_ACCESS:
          This means that it should be possible to independently decode a
          subset of the bit-stream in order to reconstruct smaller regions
          of the image.  In practice, this will almost certainly mean that
          blocks of subband coefficients are encoded independently and all
          necessary information to extract the relevant code bits is
          included in the bit-stream.
        SNR_PROGRESSIVE:
          This means that it should be possible to decode only the first
          N bytes of the bit-stream, where N is a user specified value over
          which the algorithm has no control.  Moreover, compression
          performance should be evaluated and reported in terms of PSNR vs.
          N.  For more information on this profile flag, consult the comments
          concerning the `max_bytes' argument for the
          `bitstream_source__initialize' function.
        SNR_PARSABLE:
          This means that it should be possible to parse the bit-stream in
          order to extract an N byte subset, where N is a user specified
          value over which the algorithm has no control.  This is a weaker
          requirement than SNR_PROGRESSIVE since we do not insist that the
          subset be the initial N bytes of the bit-stream.  Nevertheless, the
          parsing algorithm must be simple and should not involve any
          significant decoding tasks.  Some algorithms will produce better
          rate-distortion results when used with the SNR_PARSABLE profile,
          rather than the SNR_PROGRESSIVE profile.
        RESOLUTION_PROGRESSIVE:
          This means that the bit-stream should be organized so as to include
          all information relevant to lower resolution levels before
          information from higher resolution levels, so that truncation of
          the bit-stream corresponds to reduction in the resolution of the
          reconstructed image.  If this flag appears in the same profile as
          the SNR_PROGRESSIVE flag, the resolution-based ordering rule should
          take precedence, but within each resolution the bit-stream should
          be organized in an SNR-progressive manner.
        RESOLUTION_PARSABLE:
          This means that it should be possible to parse the bit-stream in
          order to extract a subset which represents a lower resolution image,
          for each of the resolution levels offered by the wavelet transform.
          Clearly this is a weaker requirement than RESOLUTION_PROGRESSIVE
          and most coding algorithms should have no trouble supporting it
          in conjunction with any other supported profile flags.  It should
          be noted, however, that some algorithms might produce less efficient
          bit-streams when their bit-stream are parsed down in this manner
          than they would have been able to produce if the original encoded
          image had the lower resolution to start with.
        COMPONENT_PARSABLE:
          This means that it should be possible to parse the bit-stream in
          order to extract a subset which contains a smaller number of
          components (usually colour components, but may include alpha
          channels and other information).  We do not provide a
          separate COMPONENT_PROGRESSIVE flag at this point, since this
          does not appear to be a useful organization for the bit-stream.
     Although support for as many combinations as possible is clearly
     desirable, the emphasis for the time being should probably be on
     supporting RANDOM_ACCESS, SNR_PROGRESSIVE and RESOLUTION_PARSABLE,
     since these are most likely to be considered most closely during
     evaluation of the different algorithms.

     For more information on how a particular coding algorithm should respond
     to a set of profile flags, see the comments appearing with the
     definition of the `encoder__initialize' interface function. */


/* ========================================================================= */
/* -------------------- Common Interface Definitions ----------------------- */
/* ========================================================================= */

typedef struct filter_info_obj *filter_info_ref; /* Forward declaration */

/*****************************************************************************/
/*                             filter_info_obj                               */
/*****************************************************************************/

typedef void (*filter_info__initialize__func)
  (filter_info_ref self, int decomposition, int levels, int components,
   char *component_ids[], int component_flags[], float component_base_steps[],
   int *max_bitplanes, int argc, char *argv[]);
    /* This prototype defines the form of the `initialize' interface function
       associated with the `filter_info' object, whose definition appears
       below.  The arguments have the following interpretation:
           `self' holds a reference (pointer) to the relevant `filter_info'
       object (structure), so that private state information can be accessed.
           `decomposition' identifies the type of Wavelet decomposition to
       be used.  All object implementations must support DECOMPOSITION__MALLAT,
       which is the usual hierarchical Mallat decomposition with only three
       types of subbands, namely LL_BAND, HL_BAND, LH_BAND and HH_BAND.
       Some objects may choose to implement the so-called SPACL decomposition,
       which is identified by the DECOMPOSITION__SPACL value.  In this case,
       up to 16 different subbands may be present in a given resolution level.
       Specifically, the least significant 2 bits of a subband index will
       always refer to a primary subband division into one of LL_BAND,
       HL_BAND, LH_BAND or HH_BAND, while the most significant two bits
       identify a secondary subdivision from the primary subband into further
       LL, HL, LH or HH bands, treating the primary subband as a starting
       image.
           `levels' identifies the total number of levels in the wavelet
       decomposition.  A value of 0 means that no transform is performed at
       all.  A value of 1 means that only one level of transform is performed
       to produce one instance of each type of subband.  A value
       of 2 means that the primary LL band is further decomposed and so forth.
           `components' identifies the number of separate components in the
       image which is to be compressed or decompressed.  Multiple components
       are usually used to represent colour, but they may be used for other
       purposes, such as alpha channels.  Not all components need have the
       same dimensions, but all components must have exactly the same number
       of resolution levels in their Wavelet decomposition.
           `component_ids' points to an array of character strings, with one
       ID string for each component.  The ID string identifies the filter set
       to be used for the relevant component.  This may be recognized as a
       standard filter set or else it might be interpreted as the name of a
       file containing an appropriate definition.  The interpretation is not
       defined here, except that built-in filters should have a single
       character in their ID string and the "0" character (i.e. the digit, "0")
       will always be interpreted as the Daubechies 9/7 biorthogonal filter
       set.
           `component_flags' points to an array with one integer for each
       component, which is used to signal special attributes required of
       the Wavelet filters or quantization step sizes associated with that
       component.  Information concerning these flag bits should generally
       be maintained in the bit-stream.  Currently, two flags are defined,
       namely FILTER_INFO__RADIX_QUANT and FILTER_INFO__IDEAL_QUANT.
       These both affect they way in which a single base quantization step
       size is converted into quantization step sizes for each of the subbands.
       If FILTER_INFO__RADIX_QUANT is supplied, the quantization step sizes
       will all be exact powers of 2.  In practice, this means that it will be
       difficult to achieve a particular target bit-rate unless a scalable
       coding engine is available.  If FILTER_INFO__IDEAL_QUANT is supplied,
       the Wavelet filter taps will be ignored when computing quantization
       step sizes (they will still be taken into account when computing the
       influence of a single step error on Weighted Mean Squared error,
       though).  In this case, the quantization step sizes will be computed
       as if the the Wavelet transform was orthogonal and the analysis filters
       had a power gain of 0.5, after normalization to unit DC and Nyquist
       gains for the low- and high-pass filters respectively.
           `component_base_steps' points to an array with one base quantization
       step size for each component.  The base step size is used to derive all
       other band step sizes.  The reason for pushing responsibility for
       management of the quantization step sizes into the `filter_info' object
       is that the interpretation of quantization is inherently connected with
       the set of filter taps which are used.  The base step is a relative
       value whose absolute interpretation is obtained by multiplying by the
       nominal range of the input image samples.  The actual absolute
       quantization step size which should be used in any given band is
       determined by multiplying the `base_step' value by the nominal range