kdu_compressed.h

JPEG2000压缩解压图像源码

     of our compressed data sources, nor can they be exploited by the
     `kdu_codestream' object.  In the future, however, we expect to rely
     heavily upon these functions for supporting rich client-server interaction
     in remote image browsing applications. */
  public: // Member functions
    virtual ~kdu_compressed_source()
      { // Allows destruction of source objects from the abstract reference.
        return;
      }
    virtual void close()
      /* Allows sources to be closed from the abstract base object.  Closure
         might not have meaning for some types of sources, in which case this
         convenience function need not do anything. */
      { return; }
    virtual int read(kdu_byte *buf, int num_bytes) = 0;
      /* This function must be implemented in every derived class.  It
         implements the functionality of a sequential read operation, within
         the current read scope, transferring the next `num_bytes' bytes from
         the scope into the supplied buffer.  The function must return the
         actual number of bytes recovered, which will be less than `num_bytes'
         only if the read scope is exhausted.  The default read scope is the
         entire code-stream, although the object may support tile-, precinct-,
         tile-part- or packet-oriented scopes (see below).
            The system provides its own internal temporary buffering of
         compressed data to maximize internal access efficiency.  For this
         reason, the virtual `read' function defined here will usually be
         called to transfer quite a few bytes at a time. */
    virtual int get_capabilities()
      { /* The return value is the logical OR of one or more capabilities
           flags, whose values are defined above.  The various flags have the
           following interpretation:
            * KDU_SOURCE_CAP_SEQUENTIAL: If this flag is set, the source
                 supports sequential reading of data in the order expected
                 of a valid JPEG2000 code-stream, in either code-stream or
                 tile scope.  If this flag is not set, the
                 KDU_SOURCE_CAP_TILES and KDU_SOURCE_CAP_PRECINCTS flags
                 must both be set.
            * KDU_SOURCE_CAP_SEEKABLE: If this flag is set, the source supports
                 random access via the `set_codestream_scope' function.  The
                 KDU_SOURCE_CAP_SEQUENTIAL flag must also be set.
            * KDU_SOURCE_CAP_TILES: If this flag is set, the source supports
                 restrictions of the read scope to a single tile.  In this
                 case, the `set_tile_scope' function must be implemented.  If
                 KDU_SOURCE_CAP_SEQUENTIAL is also set, the object must support
                 sequential reads of any given tile, with all tile-parts of
                 the tile concatenated for the purpose of `read' calls within
                 the tile scope.
            * KDU_SOURCE_CAP_PRECINCTS: If this flag is set, the source
                 supports restrictions of the read scope to a single precinct.
                 The KDU_SOURCE_CAP_TILES flag must also be set, but
                 KDU_SOURCE_CAP_SEQUENTIAL need not be set.  The
                 `set_precinct_scope' function must be implemented and the
                 object must be capable of presenting all packets for the
                 precinct (or all packets which are currently available --
                 e.g., in a cache) as a single concatenated stream for the
                 purpose of `read' calls from within precinct scope. */
        return KDU_SOURCE_CAP_SEQUENTIAL;
      }
    virtual bool set_codestream_scope(int offset=0)
      { /* This function should be implemented by sources which support
           sequential reading of the code-stream from any position (e.g.,
           seekable file streams).  Subsequent reads transfer data from the
           location `offset' bytes into the code-stream, from the initial
           SOC marker.  If seeking or sequential access is not supported,
           the function should return false.  If seeking is supported, the
           function should return true, even if `offset' lies beyond the
           end of the code-stream. */
        return false;
      }
    virtual bool set_tile_scope(int tnum, int tiles)
      { /* This function should be implemented by sources which support
           non-sequential code-stream organizations (e.g., the client cache
           in an interactive client-server browsing application).  Subsequent
           reads will transfer data starting from the first SOT marker of
           the indicated tile.  The caller provides the total number of tiles
           in the code-stream as a convenience.  The function should return
           false only if the non-sequential functionality is not implemented.
              There are two reasons for setting the read scope to that of a
           single tile.  The first is to allow access to the tile header; the
           second is to provide scope for subsequent `set_precinct_scope'
           calls.
              Non-sequential source objects might not support sequential
           reads beyond the end of the tile header (thereafter, the scope
           may need to be explicitly set to that of a precinct within the
           tile in order to continue reading).  If they do, all tile-parts
           for the tile should appear to have been concatenated from the
           perspective of the `read' function.  In any event, once all data
           available (or accessible) for the tile has been read, subsequent
           `read' calls will return 0 until the next change of scope. */
        return false;
      }
    virtual bool set_precinct_scope(int comp_idx, int components,
                                    int res_idx, int resolutions,
                                    int precinct_idx, int precincts,
                                    int offset=0)
      { /* This function may be implemented by sources which support
           non-sequential code-stream organizations (e.g., the client cache
           in an interactive client-server browsing application).  The
           function may be invoked only from within tile scope (see
           `set_tile_scope').  Subsequent reads will transfer data starting
           from the first packet of the precinct and continuing until no
           more packets remain (thereafter, the `read' calls should return 0
           until the read scope is changed).  The function should return
           false only if it is not implemented.  If the data are not available,
           the function should return true, but subsequent reads will return
           zero.
              Precincts are identified by their component index (from 0 to
           `components'-1), their resolution level index (from 0 to
           `resolutions'-1, where 0 identifies the LL band) and their precinct
           index (from 0 through `precincts'-1).  The caller provides the
           index bounds as a convenience, to simplify the implementation of
           non-sequential sources.
              The optional `offset' argument may be used to specify a byte
           offset from the start of the precinct data, from which reading
           should commence. */
        return false;
      }
  };

/*****************************************************************************/
/*                             kdu_compressed_target                         */
/*****************************************************************************/

class kdu_compressed_target {
  /* Abstract base class must be derived to create a real compressed data
     target with which to construct an output `kdu_codestream' object.
     Supports the generation of complex file formats. */
  public: // Member functions
    virtual ~kdu_compressed_target()
      { // Allows destruction of target objects from the abstract reference.
        return;
      }
    virtual void close()
      /* Allows targets to be closed from the abstract base object.  Closure
         might not have meaning for some types of sources, in which case this
         convenience function need not do anything. */
      { return; }
    virtual bool write(kdu_byte *buf, int num_bytes) = 0;
      /* This function must be implemented in every derived class.  It
         implements the functionality of a sequential write operation,
         transferring `num_bytes' bytes from the supplied buffer to the
         target.  The function returns true unless the transfer could not
         be completed for some reason, in which case it returns false.
            The system provides its own internal temporary buffering for
         compressed data to maximize internal access efficiency.  For this
         reason, the virtual `write' function defined here will usually be
         called to transfer quite a few bytes at a time. */
    virtual void set_target_size(int num_bytes) { return; }
      /* This function may be called by the rate allocator at any point, to
         indicate the total size of the code-stream currently being generated,
         including all marker codes.  The function may be called after some
         or all of the code-stream bytes have been delivered to the `write'
         member function; in fact, it may never be called at all.  The
         code-stream rate allocation procedure should attempt to identify the
         code-stream size as soon as it can, but this might not always be
         possible.  If the target requires knowledge of the size before
         writing the data (as, for example, when generating a JP2 box), it may
         need to buffer the code-stream data until this function has been
         called or the object is destroyed. */
  };

/*****************************************************************************/
/*                                 kdu_codestream                            */
/*****************************************************************************/

class kdu_codestream {
  /* 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.  Unlike the other
     interface classes defined below, this one has a creation function, which
     may be used to create the entire system of compressed data containers --
     tiles, tile-components, resolutions, subbands and code-blocks. There is
     currently no precinct interface exposed to the user, but the internal
     counterpart exists.  In the future, we may add such an interface to
     facilitate direct manipulation of packet data, rather than forcing
     interaction with the code-blocks themselves. */
  // --------------------------------------------------------------------------
  public: // Lifecycle member functions
    kdu_codestream() { state = NULL; }
    bool exists()
      { return (state==NULL)?false:true; }
    bool operator!()
      { return (state==NULL)?true:false; }
    KDU_EXPORT void
      create(siz_params *siz, kdu_compressed_target *target=NULL);
      /* Creates an internal `kd_codestream' object to be accessed via this
         interface, for use in compression or other code-stream generation
         operations (e.g., transcoding). The function is deliberately not
         implemented as a constructor, since robust exception handlers cannot
         cleanup partially constructed objects if an error condition is thrown
         from within a constructor (as a general rule, constructors are the
         least robust place to do significant work).  For safety, this
         function must never be invoked on a `kdu_codestream' interface which
         already contains an embedded object.  That is, `exists()' must
         return false.
            The `target' object, if supplied, receives the compressed
         JPEG2000 code-stream when or as it becomes available.
            In order to permit determination of the basic structure, the
         caller must supply a `siz' object, whose contents have been filled
         out (and finalized).  An internal copy of this object is
         made, so the caller can feel free to destroy the `siz' object
         at any point. */
    KDU_EXPORT void
      create(kdu_compressed_source *source);
      /* Creates an internal `kd_codestream' object to be accessed via this
         interface, for use in unpacking or decompressing an existing
         code-stream (retrieved via the supplied `source' object.  For the
         same reasons mentioned above, this function is deliberately not
         implemented as a constructor and cannot be used unless (or until)
         the `kdu_codestream' interface does not reference any existing
         internal object -- i.e., `exists()' must return false.
            The function reads the main header up to but not including the
         first tile-part header.  Further code-stream reading occurs on a
         strictly as-needed basis, as tile and packet information is
         accessed. */
    KDU_EXPORT void
      share_buffering(kdu_codestream existing);