kdu_compressed.h

JPEG2000压缩解压图像源码

         compressed data.
            It can happen that individual tiles have fewer quality layers.
         In this case, these tiles participate only in the rate allocation
         associated with the initial quality layers and they make no
         contribution to the later (higher rate) layers.  If no tiles have
         `num_layer_specs' quality layers, the code-stream size will be
         limited to that specified in the largest `layer_bytes' entry for
         which at least one tile has a quality layer.
            It can happen that individual tiles have more quality layers
         than the number of layer specs provided here.  Packets associated
         with all such layers will be written with the "empty packet bit"
         set to 0 -- they will thus have the minimum 1 byte representation.
         These useless packet bytes are taken into account in the rate
         allocation process, so as to guarantee that the complete code-stream
         does not exceed the size specified in a final layer spec.
            The `thresholds' argument, if non-NULL, must point to an array
         with `num_layer_specs' entries.  If the first entry in the array
         is 0, the array receives the final optimized distortion-length
         thresholds found by the rate controller, based on the length
         information supplied in `layer_bytes', as described above.
         Otherwise, the array contains thresholds which should be used
         directly to control the contents of the quality layers, ignoring
         any information in the `layer_bytes' array.  In either case, when
         the function returns, the actual lengths allocated to each
         quality layer will have been written into the `layer_bytes' array.
            For the purpose of determining appropriate threshold values, we
         point out that a threshold of 0 yields the largest possible
         output size, i.e., all bytes are included by the end of that layer.
         A slope threshold of 0xFFFF yields the smallest possible output
         size, i.e., no code-blocks are included in the layer.  In this way,
         it is possible to first recover the thresholds used by the rate
         controller when compressing one image and apply these same
         thresholds to the compression of a second image.  The functionality
         may be useful in establishing a more consistent level of quality
         across a collection of images.   It may also be used to construct
         feedback-driven rate control loops for video compression. */
    KDU_EXPORT int
      trans_out(int max_bytes = INT_MAX);
      /* Use this output function, instead of `flush' when the code-stream
         has been created by a transcoding operation which has no real
         distortion information.  In this case, the individual code-block
         `pass_slopes' values are expected to hold 0xFFFF-layer_idx, where
         layer_idx is the zero-based index of the quality layer to which the
         code-block contributes (the pass slope value is 0 if a later pass
         contributes to the same layer).  This policy is described in the
         comments appearing with the definition of "kdu_block".  A modified
         form of the rate allocation algorithm is used to write output
         quality layers with the same code-block contributions as the
         quality layers in the input code-stream which is being transcoded.
            If the existing layers exceed the `max_bytes' limit, empty
         packets are written for any complete quality layers which are to
         be discarded and partial layers are formed by discarding code-blocks
         starting from the highest frequency subbands and the bottom of the
         image.
            The function returns the number of non-empty quality layers. */
  // ------------------------------------------------------------------------
  public: // Summary information reporting functions
    KDU_EXPORT int
      get_total_bytes();
      /* Returns the total number of bytes written to or read from
         the code-stream so far. */
    KDU_EXPORT int
      get_num_tparts();
      /* Returns the total number of tile-parts written to or read from
         the code-stream so far. */
    KDU_EXPORT void
      collect_timing_stats(int num_coder_iterations);
      /* Collects timing statistics, which may later be retrieved using
         `get_timing_stats'.  If `num_coder_iterations' is non-zero, the block
         encoder or decoder will be asked to time itself (it need not
         necessarily comply) by processing each block `num_coder_iterations'
         times.  If it does so, block coder throughput statistics will also be
         reported.  If `num_coder_iterations' is 0, end-to-end times are
         generally very reliable.  Otherwise, the numerous calls to the
         internal `clock()' function required to time block coding operations
         may lead to some inaccuracies.  The larger the value of
         `num_coder_iterations', the more reliable block coding times are
         likely to be, since the coder is executed multiple times between calls
         to `clock()'.  On the other hand, the end-to-end execution time needs
         to be corrected to account for multiple invocations of the block
         coder, and this correction can introduce substantial inaccuracies. */
    KDU_EXPORT double
      get_timing_stats(int *num_samples, bool coder_only=false);
      /* If `coder_only' is false, the function returns the number of
         seconds since the last call to `collect_timing_stats'.  If a block
         coder timing loop has been used to gather more accurate block coding
         statistics by running the block coder multiple times, the function
         estimates the number of seconds which would have been consumed if
         the block coder had been executed only once per code-block.
            If `coder_only' is true, the function returns the number of
         seconds required to process all code-blocks.  If the coder was invoked
         multiple times, the returned number of seconds is normalized to the
         time which would have been required by a single invocation of the
         coder.  If the coding operation was not timed, the function returns 0.
            If `num_samples' is non-NULL, it is used to return the number of
         samples associated with returned CPU time.  If `coder_only' is true,
         this is the number of code-block samples.  Otherwise, it is the
         number of samples in the current image region.  In any event, dividing
         the returned time by the number of samples yields the most appropriate
         estimate of per-sample processing time. */
    KDU_EXPORT int
      get_compressed_data_memory();
      /* Returns the total amount of heap memory allocated to storing
         compressed data.  This includes compressed code-block bytes,
         coding pass length and R-D information and layering information.
         It does not include parsing or generation state information -- the
         amount of memory required for this is reported by
         `get_compressed_state_memory'.
            In the event that the `share_buffering' member function has been
         used to associated a single compressed data buffering service with
         multiple codestream objects, the value reported here represents the
         amount of memory consumed by all such codestream objects together. */
    KDU_EXPORT int
      get_compressed_state_memory();
      /* Returns the total amount of heap memory allocated to storing the
         state of tiles, tile-components, resolutions, subbands, precincts
         and code-blocks.  This might not be an insignificant cost, either
         for compression or decompression.  For example, even if we intend
         to discard many resolution levels, we might still need to store
         state information for all code-blocks in the resolution levels to
         be discarded, since otherwise we cannot parse packet headers and
         determine the location of the packets we want.  This depends, of
         course, on the packet progression sequence, the region of interest
         and so forth.  The system does its best to minimize the amount of
         state information which is stored at any given moment, based on
         what it knows about the user's intended access patterns (e.g.,
         whether or not the compressed data needs to be persistent). */

    // ------------------------------------------------------------------------
    private: // Interface state
      kd_codestream *state;
  };

/*****************************************************************************/
/*                                   kdu_tile                                */
/*****************************************************************************/

class kdu_tile {
  /* Objects of this class are only interfaces, having the size of a single
     pointer.  Copying the object has no effect on the underlying state
     information, but simply serves to provide another interface (or
     reference) to it.  Note that there is no destructor, because destroying
     an interface has no impact on the underlying state. */
  // --------------------------------------------------------------------------
  public: // Lifecycle member functions
    kdu_tile() { state = NULL; }
    kdu_tile(kd_tile *state) { this->state = state; }
    bool exists()
      { return (state==NULL)?false:true; }
    bool operator!()
      { return (state==NULL)?true:false; }
    KDU_EXPORT void
      close();
      /* Although not strictly necessary, it is a good idea to call this
         function once you have finished reading from or writing to a tile.
         Once closed, future attempts to access the same tile via the
         `kdu_codestream::open_tile' function will generate an error, unless
         the codestream object is set for persistence (see the
         `kdu_codestream::set_persistent' function).  With non-persistent
         codestream objects, the system is free to discard all internal storage
         associated with a closed tile at its earliest convenience.  For
         persistent codestream objects, all open tiles must be closed before
         the appearance can be modified bu `kdu_codestream::change_appearance'
         or `kdu_codestream::apply_input_restrictions'. */
  // --------------------------------------------------------------------------
  public: // Identification member functions
    KDU_EXPORT int
      get_tnum();
      /* Returns the zero-based tile index of this tile as it appears in
         the relevant code-stream. */
  // --------------------------------------------------------------------------
  public: // Data processing/access member functions
    KDU_EXPORT bool
      get_ycc();
      /* Returns true if a component colour transform is to be used for the
         first 3 image components.  In the event that the number of apparent
         components is less than 3, even though the actual number of code-stream
         components may be 3 or more, the function returns false. */
    KDU_EXPORT int
      get_num_components();
      /* Returns the apparent number of image components, which is
         also the number of tile-components in the current tile.  Note
         that this value is affected by the `max_components' argument
         supplied by any call to `kdu_codestream::apply_input_restrictions'. */
    KDU_EXPORT kdu_tile_comp
      access_component(int component_idx);
      /* Valid component indices lie in the range 0 through num_comps-1 */
  // --------------------------------------------------------------------------
  private: // Interface state
    kd_tile *state;
  };

/*****************************************************************************/
/*                                kdu_tile_comp                              */
/*****************************************************************************/

class kdu_tile_comp {
  /* Objects of this class are only interfaces, having the size of a single
     pointer.  Copying the object has no effect on the underlying state
     information, but simply serves to provide another interface (or
     reference) to it.  Note that there is no destructor, because destroying
     an interface has no impact on the underlying state. */
  // --------------------------------------------------------------------------
  public: // Lifecycle member functions
    kdu_tile_comp() { state = NULL; }
    kdu_tile_comp(kd_tile_comp *state) { this->state = state; }
    bool exists()
      { return (state==NULL)?false:true; }
    bool operator!()
      { return (state==NULL)?true:false; }
  // --------------------------------------------------------------------------
  public: // Data processing/access functions
    KDU_EXPORT bool
      get_reversible();
      /* Returns true if tile-component is to be processed reversibly. */
    KDU_EXPORT void