region_decompressor.h

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

    kdu_line_buf line; // Suitably interpolated and mapped image line.
    kdu_sample16 *lut; // Palette mapping LUT.  NULL if no palette.
  };
  /* Notes:
        The `line' buffer always holds 16-bit fixed point quantities.  When
     a palette is involved, these are obtained through the palette mapping.
     Otherwise, the values are obtained from the code-stream image component
     samples by performing appropriate conversion operations. */

/******************************************************************************/
/*                            kdr_region_decompressor                         */
/******************************************************************************/

class kdr_region_decompressor {
  public: // Member functions
    ~kdr_region_decompressor()
      { /* Deallocate resources, which might be left behind if a `finish'
           was still pending when the object was destroyed. */
        codestream_failure = true;
        finish();
      }
    void start(kdu_codestream codestream, kdr_channel_mapping *mapping,
               int single_component, int discard_levels, int max_layers,
               kdu_dims region, kdu_coords sampling);
      /* Prepares for decompression of a new region of interest.  If
         `mapping' is NULL, a single image component is to be decompressed,
         whose index is identified by `single_component'.  Otherwise, one
         or more components must be decompressed and subjected to potentially
         quite complex mapping rules to generate colour channels for display;
         the relevant components and mapping rules are identified by the
         `mapping' object.
            The `region' field identifies the image region which is to be
         decompressed.  This region is defined with respect to a rendering
         canvas on which each of the image components must have integer
         sub-sampling factors (this constraint could be dropped without too
         much difficulty, although it would make the implementation
         significantly less comprehensible.  The sub-sampling factors for the
         first colour channel (or the single image component) are given by
         the `sampling' argument. Note that these sub-sampling factors are
         not generally the same as those which describe the image components
         relative to the high resolution code-stream canvas coordinate
         system.  The sub-sampling factors for other colour channels and
         components are automatically derived from the code-stream, but they
         must also be found to have an integer relationship to the rendering
         grid.  That is, S_0*s_0 must be divisible by S_k, where the S_k
         are the code-stream sub-sampling factors, S_0 is the code-stream
         sub-sampling factor for the first channel and s_0 is the rendering
         sampling factor supplied via the `sampling' argument.  Of course,
         these relationships apply separately to each of the horizontal and
         vertical dimensions.
            The individual image components may have additional registration
         offsets, specified in the code-stream.  To clarify the relationship
         between these registration offsets and the rendering canvas, it is
         expected that all regions on the rendering canvas are derived with
         reference to the first channel (or the single image component) and
         its sub-sampling factors.  Specifically, the upper-left point on
         the rendering canvas should have coordinates
            [sampling.y*y0+floor((sampling.y-1)/2),
             sampling.x*x0+floor((sampling.x-1)/2)]
         where [y0,x0] are the coordinates of the upper-left point of the
         first channel or single image comonent.  Also, the image dimensions
         on the rendering canvas should be sampling.y*Y by sampling.x*X
         where the first channel or single image component has dimensions
         Y by X. */
    bool process(kdu_byte *buffer, int buffer_row_gap,
                 kdu_dims buffer_region, kdu_dims &incomplete_region,
                 int suggested_increment, kdu_dims &new_region);
      /* This powerful function is the workhorse of the "kdu_show" application.
         It is used to incrementally decompress an active region into the
         supplied buffer.  The function decompresses some whole number of
         lines of a single tile, where the total number of samples in those
         lines is approximately equal to the value of the `suggested_increment'
         argument, unless the value of that argument is smaller than a single
         line of the current tile, or larger than the number of samples
         remaining in the tile.  In this way, the newly decompressed lines
         are guaranteed to belong to a rectangular region -- the function
         returns this region via the `new_region' argument.  This and all
         other regions manipulated by the function are expressed in the
         rendering coordinate system (the coordinate system associated with
         the `region' argument supplied to the `start' member function).
            Decompressed samples are automatically colour transformed,
         clipped, level adjusted, interpolated and colour appearance
         transformed, as necessary.  They are then written into the supplied
         byte buffer.  The byte buffer invariably consists of interleaved
         BGR samples, so that a monochrome source's sample values will be
         replicated into each of the B, G and R planes.  The `buffer_row_gap'
         argument identifies the number of BGR pixels separating successive
         rows in the buffer.  The `buffer_region' argument identifies the
         region associated with the buffer.  Decompressed sample values which
         lie outside this region will be discarded.  This may happen for any
         number of reasons; for example, the user may scroll the window so
         that the originally requested region no longer lies entirely within
         the user's viewport.
            On entry, the `incomplete_region' structure identifies the subset
         of the original region supplied to `start', which has not yet been
         decompressed and is still relevant to the application.  It is always
         a subset of the `buffer_region'.  The function uses this information
         to avoid unnecessary processing of tiles which are no longer relevant.
            On exit, the upper boundary of the `incomplete_region' is updated
         to reflect any completely decompressed rows.  Once the region becomes
         empty, all processing is complete and future calls will return false.
            The function may return true, with `new_region' empty.  This can
         happen, for example, when skipping over a now-defunct tile.  The
         intent is to avoid forcing the caller to wait for new tiles to be
         loaded (possibly from disk).
            If the underlying code-stream is found to be sufficiently corrupt
         that the decompression process must be aborted, the current function
         will return false prematurely.  This condition will be evident from
         the fact that `incomplete_region' is non-empty.  You should still
         call `finish' and watch the return value from that function. */
    bool finish();
      /* Every call to `start' must be matched by a call to `finish'; however,
         you may call `finish' prematurely.  This allows processing to be
         terminated on a region whose intersection with a display window has
         become too small to justify the effort.
            If the function returns false, a fatal error has occurred in the
         underlying code-stream and you must destroy the codestream object
         (use `codestream.destroy').  This should clean up all the resources
         correctly, in preparation for subsequently opening a new code-stream
         for further decompression and rendering work. */
  private: // Implementation helpers
    void open_tile();
    void close_tile();
  private: // Data
    kdu_sample_allocator allocator;
    kdu_codestream codestream;
    bool codestream_failure; // True if an exception generated in `process'.
    kdu_dims valid_tiles;
    kdu_coords next_tile_idx; // Index to be used for next open tile call.
    kdu_tile current_tile;
    bool tile_open; // True if the current tile is open.
    bool use_ycc;
    kdu_dims render_dims; // Dimensions of current tile on rendering canvas
    kdr_component components[6]; // Can't need more than this number components
    int num_channels; // Number of channels to render (1 or 3).
    kdr_channel channels[3]; // Rendering output is channels, not components
    jp2_colour_space space; // For use in determining channel colour properties
    jp2_colour colour; // For use in implementing channel colour transforms
  };
  /* Notes:
        The `render_dims' member identifies the dimensions and location of the
     region which is being decompressed (a region of some tile) on the
     rendering canvas coordinate system (not the code-stream canvas coordinate
     system). Whenever a new line of channel data is produced, the
     `render_dims.pos.y' field is incremented and `render_dims.size.y' is
     decremented. */

#endif REGION_DECOMPRESSOR_H