kdu_params.h

该源码是JPEG2000的c++源代码,希望对研究JPEG2000标准以及编解码的朋友们有用.

/*****************************************************************************/
// File: kdu_params.h [scope = CORESYS/COMMON]
// Version: Kakadu, V2.2
// Author: David Taubman
// Last Revised: 20 June, 2001
/*****************************************************************************/
// Copyright 2001, David Taubman, The University of New South Wales (UNSW)
// The copyright owner is Unisearch Ltd, Australia (commercial arm of UNSW)
// Neither this copyright statement, nor the licensing details below
// may be removed from this file or dissociated from its contents.
/*****************************************************************************/
// Licensee: Book Owner
// License number: 99999
// The Licensee has been granted a NON-COMMERCIAL license to the contents of
// this source file, said Licensee being the owner of a copy of the book,
// "JPEG2000: Image Compression Fundamentals, Standards and Practice," by
// Taubman and Marcellin (Kluwer Academic Publishers, 2001).  A brief summary
// of the license appears below.  This summary is not to be relied upon in
// preference to the full text of the license agreement, which was accepted
// upon breaking the seal of the compact disc accompanying the above-mentioned
// book.
// 1. The Licensee has the right to Non-Commercial Use of the Kakadu software,
//    Version 2.2, including distribution of one or more Applications built
//    using the software, provided such distribution is not for financial
//    return.
// 2. The Licensee has the right to personal use of the Kakadu software,
//    Version 2.2.
// 3. The Licensee has the right to distribute Reusable Code (including
//    source code and dynamically or statically linked libraries) to a Third
//    Party, provided the Third Party possesses a license to use the Kakadu
//    software, Version 2.2, and provided such distribution is not for
//    financial return.
/******************************************************************************
Description:
   Defines a code-stream parameter management system.  The system manages
information which might be stored in code-stream marker segments, as well
as some information which cannot be preserved in any well-defined way
within a JPEG2000 code-stream.  The derived object names, "siz_params",
"cod_params", "qcd_params", etc., are intended to identify the association
with particular types of code-stream marker segments (SIZ, COD, QCD, etc.).
Services are provided to parse and generate such code-stream marker segments.
However, the design here is intended to provide a more uniform view of
code-stream attributes than that offered by the JPEG2000 standard's marker
segments.
   Parameters which belong together (e.g., all COD/COC type parameters) are
grouped into what we call parameter clusters.  Each cluster has a collection
of defined attributes which may be queried, textualized, translated and so
forth, in a variety of different ways.  Each cluster generally has multiple
incarnations.  The primary incarnation is known as the "tile-head", which
represents the "fall-back" attribute values to be used for all tiles, in the
event that tile- or tile-component specific information is not available.
Additional incarnations exist for every tile-component, and also as
"component-heads" (fall-back attributes for a component, when no specific
information is provided for a tile) and "tile-component" heads (fall-back
attributes for components of a specific tile, when no specific information
is provided for that tile-component).  An elaborate system is provided to
implement fall-back policies and to provide the various "lock-outs" required
to ensure that information cannot be specialized to tiles or tile-components
when that is forbidden by the standard.
   The services defined here are sensitive to the fact that code-stream
parameters may become available incrementally (say while decompressing an
existing JPEG2000 code-stream incrementally).
   Services are provided to copy a network of code-stream parameters or
transform them into suitable subsets or geometrically adjusted views, for
the benefit of transcoding applications.  These services support incremental
availability of the information.
   Services are also provided to generate human readable descriptions of
any or all of the code-stream parameter attributes and to create attributes
from descriptions in this same form (used, for example, with command-line
argument or switch-file input).  The parameters are also capable of generating
rich or comprehensive descriptions of themselves and their interpretation.
******************************************************************************/

#ifndef KDU_PARAMS_H
#define KDU_PARAMS_H

#include <assert.h>
#include <iostream>
#include "kdu_elementary.h"

// Defined here:

class kdu_params;
class siz_params;
class cod_params;
class qcd_params;
class rgn_params;
class poc_params;
class crg_params;

// Referenced here, defined elsewhere:

struct kd_attribute;

/*****************************************************************************/
/*                                kdu_output                                 */
/*****************************************************************************/

#define KDU_OBUF_SIZE 512

class kdu_output {
  /* This abstract base class must be derived to construct meaningful
     output targets.  Since there may be many low level byte-oriented
     transactions, we emphasize efficiency for such transactions. */
  public: // Member functions
    kdu_output()
      { next_buf = buffer; end_buf = buffer+KDU_OBUF_SIZE; }
    virtual ~kdu_output() { return; }
     // Derived objects should usually provide a destructor to flush the buffer
    int put(kdu_byte byte)
      { // Always returns 1.
        if (next_buf == end_buf)
          { flush_buf(); assert(next_buf < end_buf); }
        *(next_buf++) = byte;
        return 1;
      }
    int put(kdu_uint16 word)
      { // Writes the word in big-endian order and returns 2.
        put((kdu_byte)(word>>8));
        put((kdu_byte)(word>>0));
        return 2;
      }
    int put(kdu_uint32 word)
      { // Writes the word in big-endian order and returns 4.
        put((kdu_byte)(word>>24));
        put((kdu_byte)(word>>16));
        put((kdu_byte)(word>>8));
        put((kdu_byte)(word>>0));
        return 4;
      }
    void write(kdu_byte *buf, int count)
      {
        while (count > 0)
          {
            int xfer_bytes = end_buf - next_buf;
            if (xfer_bytes == 0)
              { flush_buf(); xfer_bytes = end_buf - next_buf; }
            xfer_bytes = (count < xfer_bytes)?count:xfer_bytes;
            count -= xfer_bytes;
            while (xfer_bytes--)
              *(next_buf++) = *(buf++);
          }
      }
  protected: // Data and functions used for buffer management.
    virtual void flush_buf() = 0;
      /* Flushes the buffer and returns with `next_buf' = `buffer'. */
    kdu_byte buffer[KDU_OBUF_SIZE];
    kdu_byte *next_buf; // Points to the next location to be written
    kdu_byte *end_buf; // Points immediately beyond the end of the buffer.
  };

/*****************************************************************************/
/*                                    kdu_params                             */
/*****************************************************************************/

class kdu_params {
  /* This abstract base class must be derived to one of the complete
     parameter classes defined below. Each complete parameter class
     represents the parameters embodied by a single type of code-stream
     marker segment. Parameter objects may be generated in one of three ways:
     1) from text strings which describe specific attributes (these might be
     entered on a command line); 2) from a code-stream marker segment; and
     3) by explicitly setting parameter attribute values. Parameter objects
     may be serialized in one of two ways: 1) by writing text strings which
     describe specific attributes; and 2) by writing code-stream marker
     segments.
         Parameter objects are collected into clusters, which represent
     related code-stream marker segments from different tiles and different
     image components. In particular, each kdu_params object is identified
     within a cluster by 3 coordinates: its tile index; its component index;
     and its instance index. Tile indices must start from -1; component
     indices must start from -1; and instance indices must start from 0. In
     some cases multiple components, multiple tiles or multiple instances
     will be disallowed.
         The cluster is organized firstly as a list of tiles, where the
     first object in the list must have a tile index of -1, identifying it
     as a summary object for all tiles. This object is known as the
     cluster head. Each of the objects in this first list serves as a
     "tile head" for all of the component objects associated with a tile.
     These tile head objects must have component indices of -1, identifying
     them as summary objects for all components in the tile.  A list of
     tile-component objects is built from each tile head and each of these
     serves as a component head, having an instance index of 0. It heads
     a list of one or more instances for the tile-component. */
  // --------------------------------------------------------------------------
  public: // Lifecycle functions
    KDU_EXPORT
      kdu_params(const char *cluster_name, bool allow_tile_diversity,
                 bool allow_component_diversity,
                 bool allow_instance_diversity);
      /* Constructs a new individual object, having tile and component indices
         of -1 (as is required for cluster and tile heads, respectively) and
         an instance index of 0 (as is required for tile-component heads).
         To link the object into a cluster or list of clusters, the `link'
         member function must subsequently be called. */
    KDU_EXPORT
      virtual ~kdu_params();
      /* When destroying an object which is the head of any list, the entire
         list will be destroyed. Objects with instance indices of 0 are
         tile-component heads (they destroy all instances in the
         tile-component).  Tile-component heads with component indices of -1
         are tile heads (they destroy all components in the tile).  Tile heads
         with tile indices of -1 are cluster heads (they destroy all tiles in
         the cluster).  Destroying the first cluster head in the cluster list
         causes all clusters to be destroyed. */
    KDU_EXPORT kdu_params *
      link(kdu_params *existing, int tile_idx, int comp_idx);
      /* Links the object into a list of existing object clusters, of which
         `existing' must be a member. In the process, the tile index and
         component index of the new object are replaced by the supplied values.
         Since the object being linked must have been constructed using the
         above constructor, its tile and component indices will both be -1 on
         entry. If the existing list of clusters already contains an instance
         of this tile-component, a new instance is created automatically.
         The function returns a pointer to `this', for convenience. */
    virtual kdu_params *new_instance() = 0;
      /* Adds a new instance to the current object's instance list, returning
         a pointer to the instance. The current object need not be the head
         or the tail of its instance list. The function must be overridden in
         derived classes, where it will normally invoke the relevant