kdu_sample_processing.h

JPEG2000的C++实现代码

/*****************************************************************************/
// File: kdu_sample_processing.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:
   Uniform interface to sample data processing services: DWT analysis; DWT
synthesis; subband sample encoding and decoding; and colour transformation.
Here, we consider the encoder and decoder objects to be sample data processing
objects, since they accept or produce unquantized subband samples.  They
build on top of the block coding services defined in "kdu_block_coding.h",
adding quantization, ROI adjustments, appearance transformations, and buffering
to interface with the DWT.
******************************************************************************/

#ifndef KDU_SAMPLE_PROCESSING_H
#define KDU_SAMPLE_PROCESSING_H

#include <assert.h>
#include "kdu_messaging.h"
#include "kdu_compressed.h"

// Defined here:
union kdu_sample32;
union kdu_sample16;
class kdu_sample_allocator;
class kdu_line_buf;

class kdu_push_ifc_base;
class kdu_push_ifc;
class kdu_pull_ifc_base;
class kdu_pull_ifc;
class kdu_analysis;
class kdu_synthesis;
class kdu_encoder;
class kdu_decoder;

// Defined elsewhere:
class kdu_roi_node;


/* ========================================================================= */
/*                     Class and Structure Definitions                       */
/* ========================================================================= */

/*****************************************************************************/
/*                              kdu_sample32                                 */
/*****************************************************************************/

union kdu_sample32 {
    float fval;
    kdu_int32 ival;
  };

/*****************************************************************************/
/*                              kdu_sample16                                 */
/*****************************************************************************/

#define KDU_FIX_POINT 13 // Num fraction bits in a 16-bit fixed-point value

union kdu_sample16 {
  kdu_int16 ival;
  };

/*****************************************************************************/
/*                          kdu_sample_allocator                             */
/*****************************************************************************/

class kdu_sample_allocator {
  /* This object serves to prevent excessive memory fragmentation.
     Pre-allocation requests are made by all clients which wish to use
     its services, after which a single block of memory is allocated and
     the actual allocation requests must be made -- these must be identical
     to the pre-allocation requests.  Memory chunks allocated by this
     object to a client may not be individually returned or recycled, since
     this incurs overhead and fragmentation.
        The object may be re-used (after a call to `restart()') once all
     memory served out is no longer in use.  When re-used, the object makes
     every attempt to avoid destroying and re-allocating its memory block.
     This avoids memory fragmentation and allocation overhead when processing
     images with multiple tiles or when used for video applications. */
  public: // Member functions
    kdu_sample_allocator()
      { bytes_reserved = bytes_used = buffer_size = 0;
        pre_creation_phase=true; buffer = NULL; }
    ~kdu_sample_allocator()
      { if (buffer != NULL) delete[] buffer; }
    void restart()
      { bytes_reserved = bytes_used = 0; pre_creation_phase = true; }
    void pre_alloc(bool use_shorts, int before, int after, int num_requests)
      { /* Reserves enough storage for `num_requests' later calls to `alloc16'
           (if `use_shorts' is true) or `alloc32' (if `use_shorts' is false) */
        assert(pre_creation_phase);
        before+=before; after+=after; // Two bytes per sample
        if (!use_shorts)
          { before+=before; after+=after; } // Four bytes per sample
        bytes_reserved += num_requests*(((7+before)&~7) + ((7+after)&~7));
      }
    void finalize()
      { // Call after all reservations (pre-alloc's) are in.
        assert(pre_creation_phase); pre_creation_phase = false;
        if (bytes_reserved > buffer_size)
          { // Otherwise, use the previously allocated buffer.
            buffer_size = bytes_reserved;
            if (buffer != NULL) delete[] buffer;
            buffer = new kdu_byte[buffer_size];
          }
        assert(buffer != NULL);
      }
    kdu_sample16 *alloc16(int before, int after)
      { /* Allocate an array with space for `before' entries prior to the
           returned pointer and `after' entries after the returned pointer
           (including the entry to which the pointer refers).  The returned
           pointer is guaranteed to be aligned on an 8-byte boundary. */
        assert(!pre_creation_phase);
        before = (before+3)&~3; // Round up to nearest multiple of 8 bytes.
        after = (after+3)&~3; // Round up to nearest multiple of 8 bytes.
        kdu_sample16 *result = (kdu_sample16 *)(buffer+bytes_used);
        result += before; bytes_used += (before+after)<<1;
        assert(bytes_used <= bytes_reserved);
        return result;
      }
    kdu_sample32 *alloc32(int before, int after)
      { // Same as `alloc16', but allocates 32-bit sample arrays.
        assert(!pre_creation_phase);
        before = (before+1)&~1; // Round up to nearest multiple of 8 bytes.
        after = (after+1)&~1; // Round up to nearest multiple of 8 bytes.
        kdu_sample32 *result = (kdu_sample32 *)(buffer+bytes_used);
        result += before; bytes_used += (before+after)<<2;
        assert(bytes_used <= bytes_reserved);
        return result;
      }
    int get_size()
      { /* For memory consumption statistics.  Returns the maximum size buffer
           which has every been allocated upon finalization. */
        return buffer_size;
      }
  private: // Data
    bool pre_creation_phase; // True if in the pre-creation phase.
    int bytes_reserved;
    int bytes_used;
    int buffer_size; // Must be >= `bytes_reserved' except in precreation phase
    kdu_byte *buffer;
  };

/*****************************************************************************/
/*                              kdu_line_buf                                 */
/*****************************************************************************/

class kdu_line_buf {
  /* Instances of this structure manage the buffering of a single line of
     sample values, whether image samples or subband samples.  For the
     reversible path, samples must be absolute 32- or 16-bit integers.  For
     irreversible processing, samples have a normalized representation, where
     the nominal range of the data is typically -0.5 to +0.5 (actual nominal
     ranges for the data supplied to an encoder or DWT analysis object or
     retrived from a decoder or DWT synthesis object may be explicitly set in
     the relevant constructor).  These normalized quantities may have either a
     true 32-bit floating point representation or a 16-bit fixed-point
     representation.  In the latter case, the least significant
     `KDU_FIX_POINT' bits of the integer are interpreted as binary fraction
     bits, so that 2^{KDU_FIX_POINT} represents a normalized value of 1.0.
        For simplicity, the object always allocates space to allow access to
     2 samples before the first nominal sample and 8 samples after the last
     nominal sample.  This should prove more than sufficient to accommodate
     the needs of boundary extension schemes and efficient SIMD (multi-word)
     implementations of the sample data transformations. */
  // --------------------------------------------------------------------------
  public: // Life cycle functions
    kdu_line_buf()
      { destroy(); }
    void pre_create(kdu_sample_allocator *allocator,
                    int width, bool absolute, bool use_shorts)
      { /* Declares the characteristics of the internal storage which will
           later be created by `create'.  If `use_shorts' is true, the sample
           values will have 16 bits each and normalized values will use a
           fixed point representation with KDU_FIX_POINT fraction bits.
           Otherwise, the sample values have 32 bits each and normalized
           values use a true floating point representation. */
        assert((!pre_created) && (this->allocator == NULL));
        this->width=width; this->short_ints = use_shorts; 
        this->absolute_ints=absolute; this->allocator = allocator;
        allocator->pre_alloc(use_shorts,2,width+8,1);
        pre_created = true;
      }
    void create()
      { /* Finalizes creation of storage which was initiated by `pre_create'.
           Does nothing at all if the `pre_create' function was not called,
           or the object was previously created and has not been destroyed.
           Otherwise, you may not call this function until the `allocator'
           supplied to `pre_create' has had its `finalize' member function
           called.  Automatically sets the state to active. */
        if (!pre_created) return;
        pre_created = false;
        if (short_ints)
          buf16 = allocator->alloc16(2,width+8);
        else
          buf32 = allocator->alloc32(2,width+8);
        active = true;
      }
    void destroy()
      { /* Restores the object to its uninitialized state ready for a new
           `pre_create' call. */
        width=0; absolute_ints=false; short_ints=false; pre_created=false;
        allocator=NULL; buf16=NULL; buf32=NULL; active=false;
      }
    void deactivate()
      { /* You can re-activate a line which has been deactivated, but not
           one which has been destroyed. */
        active = false;
      }
    void activate()
      { /* Use to re-activate a line which has been de-activated. */
        assert((!active) && (!pre_created) &&
               ((buf32 != NULL) || (buf16 != NULL)));
        active = true;
      }
    bool is_active()
      { return active; }
    bool operator!()
      { return !active; }
  // --------------------------------------------------------------------------
  public: // Access functions
    kdu_sample32 *get_buf32()
      { /* Returns NULL if the object is not active, or data is 16 bits.
           Otherwise, returned buffer is large enough to accommodate indices
           ranging from -2 to `get_width()'+8.  See introductory comments. */
        return ((!active) || short_ints)?NULL:buf32;
      }
    kdu_sample16 *get_buf16()
      { /* Returns NULL if the object is not active, or data is 32 bits.
           Otherwise, returned buffer is large enough to accommodate indices
           ranging from -2 to `get_width()'+8.  See introductory comments. */
        return (active && short_ints)?buf16:NULL;
      }
    int get_width()
      { // Returns 0 if  the object has not been created.
        return width;
      }
    bool is_absolute()
      { return absolute_ints; }