ifc.h

JPEG2000实现的源码

once internally.  In this way, existing implementations which do not follow
the push paradigm can be readily incorporated into the framework.  Ultimately,
however, the implementation should be modified to take advantage of whatever
incremental processing capabilities it advertises so that resource
consumption can be fairly compared.

In the decompressor, the dual of the compressor's push paradigm is a
pull model.  Image samples are pulled out of the wavelet synthesis stage one
line at a time by means of a call to the `synthesis' object's `pull_line'
function; in order to satisfy this request, the `synthesis' stage will need
to pull subband samples from the `dequantizer', which in turn pulls samples
out of the `decoder'; ultimately, the `decoder' pulls the bit-stream from a
`stream_in' object, which will usually be equivalent to reading from
the compressed file.

**************************/
/**** Types of Objects ****

In the above discussion, we focused on what might be termed "pipeline" objects;
i.e., those objects whose functions are involved in the efficient exchange
of image data between the raw image domain and the compressed bit-stream.
In addition to "pipeline" objects, we also have some "informative" objects,
which are not directly involved in the data processing pipeline, but supply
information required by one or more pipeline objects.  Currently, the `info'
and the `roi' objects are the only example of non-pipeline objects.  The
`info' objects maintains appropriately digested and manipulated information
concerning such parameters as the Wavelet transform structure and kernels and
the quantization step sizes and interpretations.  The `roi' objects maintain
information identifying the membership of different image regions to so-called
"Regions of Interest", which is used by the coding objects to generate and
interpret the bit-stream appropriately.

The following diagram depicts the relationship between the pipeline and
non-pipeline objects used during compression.

                             forward_info -----> forward_roi
                ______________/  /  \  \___________    |
               |             __/      \__          |   |
               |            |            |         |   |
(in) -> component_mix -> analysis -> quantizer -> encoder -> stream_out

Similarly, the following diagram depicts the relationship between the pipeline
and non-pipeline objects used during decompression.

                                   reverse_info -----> reverse_roi
                  __________________/  /  \  \___________    |
                 |               ____/      \__          |   |
                 |              |              |         |   |
(out) <- component_demix <- synthesis <- dequantizer <- decoder <- stream_in

****************************/
/**** Concluding Remarks ****

We hope that the comments provided in the remainder of this header file will
clearly identify the role played by each object and its interface functions.

****************************/

/* ========================================================================= */
/* --------------- Modular Command Line Argment Management ----------------- */
/* ========================================================================= */

 /********************
    Each of the objects defined in this header file has the opportunity to
    derive usage information from the command line arguments supplied
    to the encapsulating program.  To facilitate modular, independent command
    line argument processing throughout the entire compression/decompression
    system, access to the command-line arguments is granted through a special
    object, `cmdl', whose definition appears later in the file.
        Each object's `initialize' function receives a reference to the `cmdl'
    object.  It extracts arguments and any parameters via the interface
    function `cmdl__extract'.  This enables some preparsing of the complex
    command-line argument structure and also provides a mechanism for
    determining whether command-line arguments were recognized by at least
    one module (see comments appearing with the `cmdl__terminate' function
    definition below for a precise definition of argument recognition).
        Command line arguments must be strings (in the original ANSI C
    `argv' array) consisting of a `-' character, followed by an alphabetical
    character.  Intervening entries in the original ANSI C `argv' array
    are considered to be parameters to the last argument.  Command-line
    arguments are extracted via an `arg' string supplied to the
    `cmdl__extract' function.  In the simplest case, this string is identical
    to the actual argument string used on the command line.  For many
    argument strings, however, there is a second form in which the `arg'
    string is followed immediately by a zero-based tile index, enclosed in
    angle characters, `{' and `}', without any intervening space.  Thus,
    as an example, the argument "-Flev" may appear on the command-line as
    "-Flev{0}" if specific information is being provided for the first
    tile in the image.  When both forms are present, the non-specific form
    is used for all tiles which do not have a tile-specific form.  The
    `cmdl__extract' function facilitates parsing of arguments following
    these conventions.
            Each object's interface also contains a `get_usage' function, which
    must return either NULL, or else a pointer to a NULL-terminated array of
    character strings.  The argument should be NULL only if the object does
    not recognize any arguments.  Otherwise, it must point to an array
    containing an even number of character strings, followed by a NULL
    character string pointer.  Each argument is represented by a pair of
    consecutive character strings, which have the following interpretations.
        The first string in each pair must commence with the name of the
    argument, e.g. "-Bprint_header" to request a print-out of the global
    header from the `stream_in' or `stream_out' object.  The name must not
    contain spaces, but may be followed by additional descriptive text, which
    must be separated by spaces from the argument name.  The idea is that this
    descriptive text should represent a summary of the parameters which might
    appear in a usage summary.  Thus, in a more complex example, we have
    "-Fdecomp mallat|spacl|packet|<decomp string>", which indicates that
    the `-Fdecomp' argument takes a single parameter which may be one of
    the pre-defined strings, `mallat', `spacl' or `packet', or else it may
    be a custom decomposition string.  Finally, our first string in each
    pair may contain a trailer consisting of a description of the default
    behaviour, enclosed within parentheses.  Thus, in our example we might
    have
      "-Fdecomp mallat|spacl|packet|<decomp string> (default=mallat)"
    If the parentheses are found within this string, the caller should assume
    that the argument is optional.  Otherwise, the argument is taken to be
    mandatory.  If the argument takes no parameters at all, as in the
    `-Bprint_header' example, it is assumed to be optional (i.e. a switch).
    Information concerning whether an argument is optional or mandatory may be
    helpful in constructing appropriate usage statements at a higher level.
        The second string in each pair contains a description of the
    argument.  Descriptions may be of any length at all and they need not
    be explicitly formatted using spaces and new-line characters, since the
    formatting will be applied automatically when printing usage statements.
        Finally, it should be noted that the NULL-terminated array of character
    strings and the strings themselves should all be static resources, declared
    at compile time.  Thus, the implementation of the `forward_info' object
    contains a declaration of the form:
        static char **args[] =
          {"-Fdecomp [mallat|spacl|packet|<decomp string>]  (default=mallat)",
             "This argument may be used to specify the spatial decomposition "
             "tree, within the constraints imposed by VM3A.  The single "
             "string parameter may be one of \"mallat\", \"spacl\" or "
             "\"packet\", or it may be a string of digits in the range 1 to "
             "3.  The first digit identifies the `max_hp_descent' value for "
             "resolution level 1; this specifies the subband structure "
             "required to recover resolution level 1 from the lowest "
             "resolution (level 0), i.e. the LL band.  The second digit "
             "identifies the `max_hp_descent' value for resolution level 2 and "
             "so forth.  For an explanation of the interpretation of these "
             "`max_hp_descent' values, the reader is referred to the thorough "
             "documentation in the master \"ifc.h\" header file.  The Mallat "
             "decomposition itself, corresponds to the string, "
             "\"1111...\".  As for the `-Fkernels' argument, if a "
             "user-defined decomposition string is longer than the number "
             "of resolution levels, trailing digits are ignored.",
           NULL};
    See the implementation for the full declaration, including all argument
    description strings.
 ********************/

/* ========================================================================= */
/* --------------- Initialization and Termination Sequence ----------------- */
/* ========================================================================= */

 /********************
   The various objects in the compression and decompression systems
   depend upon each other in complex ways.  In particular, they cannot
   be initialized and terminated in any order whatsoever.  Moreover, because
   each object's initialization function may augment the global header of
   the bit-stream, it is important that the initialization sequence be
   consistent for compression and decompression.  The initialization
   and termination sequences are as follows:

   COMPRESSION                         DECOMPRESSION
   -----------                         -------------
   stream_out__initialize              stream_in__initialize
   forward_info__initialize            reverse_info__initialize
   forward_roi__initialize             reverse_roi__initialize
   encoder__initialize                 decoder__initialize
   quantizer__initialize               dequantizer__initialize
   analysis__initialize                synthesis__initialize
   component_mix__initialize           component_demix__initialize

   (work through image tiles one       (work through image tiles one
    at a time, pushing tile lines       at a time, pulling tile lines
    into `component_mix' object         from `component_demix' object
    one at a time) ...                  one at a time) ...

    component_mix__terminate           component_demix__terminate
    analysis__terminate                synthesis__terminate
    quantizer__terminate               dequantizer__terminate
    encoder__terminate                 decoder__terminate
    forward_roi__terminate             reverse_roi__terminate
    forward_info__terminate            reverse_info__terminate
    stream_out__terminate              stream_in__terminate

    Notice that the termination sequence is not exactly the reverse of
    the initialization sequence.
 ********************/

/* ========================================================================= */
/* --------------- Interpretation of Level and Band Indices ---------------- */
/* ========================================================================= */

 /********************
    Many of the interface functions defined in this header file take
    arguments identifying a resolution level index and often a band index
    within that resolution level.  Since this is so common, it makes sense
    here to outline the uniform interpretation which is to be attached to
    these indices in terms of the different types of Wavelet decomposition
    which are supported.

    To begin, we assign a number of resolution levels, K, to the Wavelet
    decomposition associated with any given image component.  If K = 0, there