ifc.h

JPEG2000实现的源码

/*****************************************************************************/
/* Copyright 1998, Hewlett-Packard Company                                   */
/* All rights reserved                                                       */
/* File: "ifc.h"                                                             */
/* Description: Contains all exposed object interface definitions.           */
/*              This file is central to the entire VM and should be          */
/*              consulted on all questions of definition & interpretation.   */
/* Author: David Taubman                                                     */
/* Affiliation: Hewlett-Packard and                                          */
/*              The University of New South Wales, Australia                 */
/* Version: VM9.0                                                            */
/* Last Revised: 20 April, 2001                                              */
/*****************************************************************************/

/*****************************************************************************/
/* Modified by David Taubman to include masking-sensitive distortion         */
/* calculations for R-D optimization (`-Cvis' option).  Material identified  */
/* by "David T Cvis mod" comments has been added by David Taubman; it is     */
/* copyrighted by the University of New South Wales (Copyright 1999) with    */
/* all rights reserved for the modified parts.                               */
/*****************************************************************************/

/*****************************************************************************/
/* Modified by David Taubman to support arbitrary reference points for the   */
/* transform and the various regular partitions, so as to facilitate         */
/* cropping and geometric transformations in the compressed domain and to    */
/* enable full support for CRF's single-sample overlap Wavelet transform,    */
/* as originally documented in Seoul.  Changes are too numerous to flag      */
/* individually within the code.  Changes copyrighted by HP with all rights  */
/* reserved for the modified parts.                                          */
/*****************************************************************************/

/*****************************************************************************/
/* Modified by David Taubman to reflect slight modifications in the canvas   */
/* coordinate system conventions.  Changes copyrighted by HP with all rights */
/* reserved for the modified parts.                                          */
/*****************************************************************************/

/*****************************************************************************/
/* Modified by David Taubman to improve global header communication with the */
/* stream objects and to cleanup interface functions to reflect              */
/* the actual scope of the JPEG2000 standard.  Changes                       */
/* copyrighted by HP with all rights reserved for the modified parts.        */
/*****************************************************************************/

/*****************************************************************************/
/* Modified by Ali Bilgin to support wavelet transforms across the component */
/* direction. Copyright 2000 University of Arizona, Arizona Board of Regents.*/
/* All rights reserved for the modified parts.                               */
/*****************************************************************************/

/*****************************************************************************/
/* Modified by David Taubman to allow overlapping tiles.  Changes            */
/* copyrighted by HP with all rights reserved for the modified parts.        */
/*****************************************************************************/

/*****************************************************************************/
/* Modified for general wavelet decompositions.                              */
/* Copyright 2000 Science Applications International Corporation (SAIC).     */
/* Copyright 1995 University of Arizona, Arizona Board of Regents.           */
/* All Rights Reserved for modified parts.                                   */
/*****************************************************************************/

/*****************************************************************************/
/* Modified for general offset and scalar quantization.                      */
/* Copyright 2000 The MITRE Corporation.                                     */
/* All Rights Reserved for modified parts.                                   */
/*****************************************************************************/

/*****************************************************************************/
/* Modified by David Taubman to incorporate changes to the POC marker (used  */
/* to be POD).  Changes are quite extensive and not always explicitly        */
/* When flagged, the relevant comment string is "DST POC mod".               */
/* Copyright 2000 The University of New South Wales.                         */
/* All rights reserved for the modified parts.                               */
/*****************************************************************************/

/*****************************************************************************/
/* Modified by Jianxin Wei, Australian Defence Force Academy (ADFA)          */
/* to implement the Odd Tile-Size Low-Pass First Convention (OTLPF_CONVENTION)*/
/* Copyright 2000 University of New South Wales, Australia.                  */
/* All rights reserved for modified parts.                                   */
/*****************************************************************************/

#ifndef IFC_H
#define IFC_H
#include <limits.h>

/* ========================================================================= */
/* ------------------------ Introductory Comments -------------------------- */
/* ========================================================================= */

/**** PURPOSE ****

This header file contains interface definitions which clearly delineate the
roles which should be played by the transform, quantizer, entropy coder and
other conceptual objects within the JPEG2000 standard.  The definitions
are designed to support and encourage an implementation which is suitable
for memory constrained applications.  Memory constrained applications are
those applications in which the image which is to be compressed is too large
to store in memory.  During compression, for example, this means that the
image will only be seen once and that a suitable bit-stream must be generated
in one pass, using only modest intermediate buffering.

***************************/
/**** OBJECTS in ANSI C ****

Because incremental compression and decompression must be supported, local
state information must be maintained by the transform, quantizer, coding
and other stages in a conceptual pipeline.  This immediately suggests an
object-oriented solution.  Rather than introducing C++ concepts, with which
some readers may not be familiar, we stick entirely to the ANSI C programming
language, but we adopt a number of conventions which should be extremely
helpful to all concerned.  Conceptually, the transform, the quantizer and the
coder are each objects, which simply means that they are represented by
structures which hold their state and that data flows between them via
well-defined function calls and not by direct manipulation of the individual
fields in the structures.  In fact, the contents of the structures should
remain entirely private to the individual implementations of the different
stages in the compression system.  Consequently, in this header file we define
only the form of the function calls supported by each "object" and the type
definitions for the relevant structures (i.e. the different classes of
objects).  We refer to the set of functions defined for each object as its
"interface" since all interaction takes place via these functions.

We illustrate the conventions with an example, before providing the actual
interface definitions for the suggested objects.  Consider the wavelet
transform analysis stage.  The analysis task is encapsulated within a
single object, which we will call "analysis_obj".  This is just a structure
whose definition might be as follows (the real definition is a little more
complex, but this is just an example):

  typedef
    struct analysis_obj {
      initialize_func_defn initialize;
      push_func_defn push_line;
      terminate_func_defn terminate;
    } analysis_obj, *analysis_ref;

When the compression program is started, it first calls a function provided
by the implementor of the wavelet analysis stage which creates a structure
of this type and returns a reference (pointer) to the structure, i.e. something
of type `analysis_ref'.  In practice, this function allocates a structure which
is larger than that defined above so as to be able to store all relevant
private state information.  That is to say, a separate source file which wraps
up the wavelet analysis implementation might include a private definition of
a larger structure of the form,

  typedef
    struct my_analysis_obj {
      analysis_obj base;
      ... // Private data fields
      ... // Private data fields
    } my_analysis_obj;

The externally visible portion of this structure contains only a set of
function pointers.  In this case, the `initialize', `push_line' and `terminate'
functions constitute the entire interface.  The definitions of these functions
are provided through separate typedef statements, together with comments
which carefully describe the roles played by each interface function.  Each
interface function takes a reference to the object (structure) itself as its
first argument so that the state information can be readily retrieved.  Thus,
for example, the `terminate' function's definition would look like this:

  typedef void (*terminate_func_defn)(analysis_ref self);

We apologize to those of you who are not used to working with function
pointers in C.  The C++ language was created in part to overcome some of this
ugliness, but that is of no help to us here.

The interface definitions have been carefully designed to accommodate the
needs of all algorithms (as far as we are aware), while minimizing the
burden on individual algorithm proposers to implement these interfaces.
The needs of line-, block- and tree-based coding and wavelet transform
algorithms, as well as both scalar and TCQ quantization, were all considered
during the interface design.  Of course, the interface definitions may still
need to migrate as new ideas come to light, but the definitions should be
allowed to change only as a course of last resort; the interface should
not be changed just to suit the quirks of one particular implementation
(hackers beware)!!

******************************/
/**** PUSH AND PULL MODELS ****

The interface definitions layed out in this header file follow a common and
eminently justifiable paradigm for compression software.  The various stages of
the compression process uniformly adhere to a so-called "push" model: image
samples are pushed into the wavelet analysis stage one line at a time; the
wavelet analysis stage pushes subband samples to the quantization stage as
soon as they can possibly be made available (of course, it doesn't wait to
transform the entire image); likewise, the quantization stage pushes quantized
symbol indices to the encoding stage, as soon as they become available, which
ultimately pushes compressed bits to a `stream_out' object.  In practice,
this process of pushing information downstream as soon as it is available is
accomplished by calling a `push' function in the relevant object's interface.
Part of the goal here is to correctly apportion responsibility for memory
consumption amongst the different stages in the overall compression system.
For example, the order in which data is pushed to the encoder is always that
which minimizes the resource consumption in the wavelet analysis stage; this
is the sequence which hands subband samples off as soon as they can possibly
be made available.  If this sequence does not agree with the order in which
the coder would like to consume subband samples then it must incur the
relevant buffering overhead.  Of course, in individual implementations there
is no reason why an algorithm cannot wait for all sample in the entire image
to be pushed in via its `push' call, buffering them up to be processed all at