kdu_compressed.h

JPEG2000压缩解压图像源码

      /* When two or more codestream objects are to be used simultaneously,
         considerable memory can be saved by encouraging them to use the same
         underlying service for buffering compressed data.  This is because
         resources allocated for buffering compressed data are not returned to
         the system heap until the object is destroyed.  By sharing buffering
         resources, one code-stream may use excess buffers already freed up
         by the other code-stream.  This is particularly beneficial when
         implementing transcoders.  The internal buffering service will not
         be destroyed until all codestream objects which are sharing it have
         been destroyed, so there is no need to worry about the order in
         which the codestream objects are destroyed. */
    KDU_EXPORT void
      set_persistent();
      /* The persistent mode is important for interactive applications.  By
         default, tiles, precincts and code-blocks will be discarded as soon
         as it can be determined that the user will no longer be accessing
         them.  Moreover, after each code-block has been opened and closed,
         it will automatically be discarded.  This behaviour minimizes memory
         consumption when the image (or some region of interest) is to be
         decompressed only once.  For interactive applications, however, it may
         be desirable to leave the code-stream intact and permit multiple
         accesses to the same information so that a new region or resolution of
         interest can be defined and decompressed at will.  For these
         applications, you must invoke this member function before any
         attempt to access (i.e., open) an image tile. */
    KDU_EXPORT void
      destroy();
      /* Note: providing an explicit destructor for `kdu_codestream' is
         dangerous, since it is merely a container for a hidden reference to
         the `kd_codestream' object.  The interpretation of copying should
         be (and is) generating another reference, so the underlying object
         should not be destroyed when the copy goes out of scope.  Reference
         counting would be an elegant, though tedious and less explicit
         way of avoiding this difficulty.
            Destroys the internal representation, along with all tiles,
         tile-components and other subordinate state information for which
         interfaces are described in this header.  Cleanup operations may
         include flushing internal compressed data to an output code-stream
         file if one exists. */
  // --------------------------------------------------------------------------
  public: // Member functions used to access information
    KDU_EXPORT siz_params *
      access_siz();
      /* Every `kdu_codestream' object has a unique `siz_params' object which
         is the head of its parameter list.  The caller may use the object's
         member functions to parse command line arguments, copy parameters
         between code-streams and so forth.  Be careful to note, however, that
         the codestream object supports geometrically transformed views of
         the image, which are not reflected in the underlying code-stream
         parameters. */
    KDU_EXPORT int
      get_num_components();
      /* Returns the apparent number of image components. This is affected by
         any call to `kdu_codestream::apply_input_restrictions'. */
    KDU_EXPORT int
      get_bit_depth(int comp_idx);
      /* Get the bit-depth of one of the image components.  The interpretation
         of the component index is affected by the component range arguments,
         `first_component' and `max_components', supplied in any call to
         `kdu_codestream::apply_input_restrictions'. */
    KDU_EXPORT bool
      get_signed(int comp_idx);
      /* Returns true if the image component originally had a signed
         representation; false if it was unsigned.  The interpretation of
         the component index is affected by the component range arguments,
         `first_component' and `max_components' supplied in any call to
         `kdu_codestream::apply_input_restrictions'. */
    KDU_EXPORT void
      get_subsampling(int comp_idx, kdu_coords &subs);
      /* Returns the canvas sub-sampling factors for this image component.
         Note that the interpretation of the component index is affected by
         the component range arguments, `first_component' and `max_components',
         supplied in any call to the `apply_input_restrictions' function.
         Also, the sub-sampling factors are affected by the `transpose'
         argument supplied in any call to the `change_appearance' member
         function.
            The sub-sampling factors identify the separation between the
         notional centres of the component samples on the high resolution
         code-stream canvas.  Since component dimensions are affected
         by discarding resolution levels, but this has no impact on the
         high resolution canvas coordinate system, the sub-sampling factors
         returned by this function are corrected (shifted up) to accommodate
         the effects of discarded resolution levels as specified in any
         call to `apply_input_restrictions'. */
    KDU_EXPORT void
      get_registration(int comp_idx, kdu_coords scale, kdu_coords &crg);
      /* Returns component registration information for the indicated
         image component.  The horizontal and vertical registration offsets
         are returned in `creg' after scaling by `scale' and rounding to
         integers.  Samples from this component have horizontal locations
         (kx + crg.x/scale.x)*subs.x and vertical locations
         (ky + crg.y/scale.y)*subs.y, where kx and ky are integers ranging
         over the bounds returned by the `get_dims' member function and
         subs.x and subs.y are the sub-sampling factors for this component.
         The component offset information is recovered from any CRG marker
         segment in the code-stream; the default offsets of 0 will be used
         if no such marker segment exists.
            The interpretation of the component index is affected by
         the component range arguments, `first_component' and `max_components'
         supplied in any call to the `apply_input_restrictions' function.
         The registration offsets and `scale' argument are also corrected
         to account for the effects of any prevailing geometric
         transformations which may have been applied through a call to the
         `change_appearance' member function. */
    KDU_EXPORT void
      get_dims(int comp_idx, kdu_dims &dims);
      /* Returns the apparent dimensions and position of an image component
         on the canvas.  These are calculated from the image region on the high
         resolution canvas and the individual sub-sampling factors for the
         image component.  Note that the apparent dimensions are affected by
         any calls which may have been made to `kdu::change_appearance' or
         `kdu_codestream::apply_input_restrictions'.  In particular, both
         geometric transformations and resolution reduction requests affect
         the apparent component dimensions.  The interpretation of the
         component index is also relative to any restrictions on the range
         of apparent image components.
             If `comp_idx' is negative, the function returns the dimensions
         of the image on the high resolution canvas itself.  In this case, the
         return value is corrected for geometric transformations, but not
         resolution reduction requests.  Since the sub-sampling factors
         returned by `get_subsampling' are corrected for resolution reduction
         requests, the caller may recover the image component dimensions
         directly from the canvas dimensions returned here, by applying the
         sub-sampling factors.  For information on how to perform such
         mapping operations, see Chapter 11 in the book by Taubman and
         Marcellin. */
    KDU_EXPORT void
      get_valid_tiles(kdu_dims &indices);
      /* Returns the range of tile indices which correspond to the current
         region of interest (or the whole image, if no region of interest has
         been defined).  The indices of the first tile within the region of
         interest are returned via `indices.pos'.  Note that these may be
         negative, if geometric transformations were specified via
         `kdu_codestream::change_appearance'.  The number of tiles in each
         direction within the region of interest is returned via
         `indices.size'. Note that tile indices in the range pos through
         pos+size-1 are apparent tile indices, rather than actual code-stream
         tile indices.  They are affected not only by the prevailing region of
         interest, but also by the geometric transformation flags supplied
         during any call to `kdu_codestream::change_appearance'.  The caller
         should not attempt to attach any interpretation to the absolute
         values of these indices. */
    KDU_EXPORT bool
      find_tile(int comp_idx, kdu_coords loc, kdu_coords &tile_idx);
      /* Locates the apparent tile indices of the tile-component, which
         contains the indicated location (it is also an apparent location,
         taking into account the prevailing geometric view and the number
         of discarded levels). Note that the search is conducted within the
         domain of the relevant image component.  Returns false if the
         supplied coordinates lie outside the image or any prevailing
         region of interest. */
    KDU_EXPORT void
      get_tile_dims(kdu_coords tile_idx, int comp_idx, kdu_dims &dims);
      /* Same as `get_dims' except that it returns the location and dimensions
         of only a single tile (if `comp_idx' is negative) or tile-component.
         The tile indices must lie within the range identified by the
         `get_valid_tiles' function.  As with `get_dims', all coordinates and
         dimensions are affected by the prevailing geometric appearance
         and constraints set up using `kdu_codestream::change_appearance'
         and `kdu_codestream::apply_input_restrictions'.  As a result, the
         function returns the same dimensions as those returned by the
         `kdu_tile_comp::get_dims' function provided by the relevant
         tile-component; however, the present function has the advantage that
         it can be used without first opening the tile -- an act which may
         consume substantial internal resources and code-stream parsing. */
    KDU_EXPORT int
      get_max_tile_layers();
      /* Returns the maximum number of quality layers seen in any tile
         opened so far.  The function returns 1 (smallest number of allowable
         layers) if the no tiles have yet been opened. */
    KDU_EXPORT void
      map_region(int comp_idx, kdu_dims comp_region, kdu_dims &hires_region);
      /* Maps a region of interest, specified in the domain of a single image
         component onto the high-res canvas, yielding a region suitable for
         use with the `apply_input_restrictions' member function.  The supplied
         region is specified with respect to the same coordinate system as
         that associated with the region returned by `get_dims' -- i.e., taking
         into account component sub-sampling factors, discarded resolution
         levels and any geometric transformations (see `change_appearance')
         associated with the current appearance.  The component index is
         also interpreted relative to any restrictions on the range of
         available image components.  The region returned via
         `hires_region' lives on the high-res canvas of the underlying
         code-stream and is independent of appearance transformations,
         discarded resolution levels or component-specific attributes.  The
         hi-res region is guaranteed to be large enough to cover all samples
         belonging to the intersecton between the supplied component region
         and the region returned via `get_dims'. */
  // --------------------------------------------------------------------------
  public: // Member functions used to modify behaviour
    KDU_EXPORT void
      set_textualization(std::ostream *stream);
      /* Supplies an output stream to which code-stream parameters will
         be textualized as they become available.  Main header parameters
         are written immediately, while tile-specific parameters are written
         at the point when the tile is destroyed.  This function is legal
         only when invoked prior to the first tile access.  Note that the
         specification of regions of interest without persistence (see
         `kdu_codestream::apply_input_restrictions' and
         `kdu_codestream::set_persistent') may prevent some tiles from actually
         being read -- if these contain tile-specific parameters, they may
         not be textualized. */
    KDU_EXPORT void
      set_max_bytes(int max_bytes);
      /* If used with an input codestream object, this function sets the
         maximum number of bytes which will be read from the input code-stream.
         Additional bytes will be discarded.
            If used with an output codestream object, this function enables
         internal machinery for incrementally estimating the parameters which
         will be used by the PCRD-opt rate allocation algorithm, so that the
         block coder can be given feedback to assist it in minimizing the
         number of coding passes which must be processed -- in many cases, most
         of the coding passes will be discarded.  Note that the actual rate
         allocation performed during a call to the `flush' member function is
         independent of the value supplied here, although it is expected that
         `max_bytes' will be equal to the maximum layer byte count supplied in
         the `flush' call.  The following cautionary notes should be
         observed concerning the incremental rate control machinery enabled
         when this function is invoked on an output codestream: