kdu_params.h

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

         a tile-specifier of the form "T<num>", a component-specifier of the
         form "C<num>", or both. Tile and component numbers start from 0.
         If a tile-component specifier is disallowed or does not correspond
         to a valid object, the function generates an error message.
            The string concludes with an '=' sign followed by one or more
         records, delimited by commas. Multiple records are disallowed unless
         the attribute was defined with the MULTI_RECORD flag. Each record
         contains one or more fields, surrounded in curly braces.  In the
         special case where there is only one field per record, the braces may
         be skipped. The fields must match the type specifications provided in
         the `pattern' string with which the attribute was defined. Any
         failure to obey these rules will cause an error message to be
         generated.
            Attribute parsing is unlike the binary or marker based attribute
         setting functions, in several respects.  Firstly, it is illegal to
         parse the same attribute twice -- an appropriate error message will
         be generated if information has already been parsed into the
         attribute.  The only exception to this rule applies to objects which
         support multiple instances, in which case a new instance of the
         object will be created automatically to accommodate multiple
         occurrences of the same attribute string.  The multiple instances rule
         does not apply to attributes which has been set by means other than
         parsing.  Quite to the contrary, any information set by any other
         means is automatically deleted before parsing new information into an
         attribute.  More than that, if the attribute string does not specify
         a particular component, the same attribute will be deleted across all
         components which do not already contain parsed information for the
         attribute.  Similarly, if the attribute string does not specify a
         particular tile, the same attribute will be deleted across all tiles
         which do not already contain parsed information.  This functionality
         is intended to reflect the most likely intention of a transcoding user
         who wishes to modify some parameter attributes of an existing
         code-stream prior to transcoding. */
    KDU_EXPORT bool
      parse_string(char *string, int tile_idx);
      /* Same as above, but parses only those strings which refer
         to the indicated tile.  As usual, a tile index of -1 refers to
         the summary object for all tiles. */
    KDU_EXPORT void
      textualize_attributes(std::ostream &stream, bool skip_derived=true);
      /* Textualizes all attributes for which information has been written,
         using the same format as described above for `parse_string' and
         writing the result out to the supplied stream.  The `skip_derived'
         argument controls whether or not attributes marked as holding
         automatically derived quantities (using the `set_derived' member
         function) should be skipped over. */
    KDU_EXPORT void
      textualize_attributes(std::ostream &stream, int min_tile, int max_tile,
                            bool skip_derived=true);
      /* Same as above, with two important differences: 1) only objects whose
         tile indices lie between `min_tile' and `max_tile' (inclusive) have
         their attributes textualized; and 2) the function textualizes all
         objects which lie within a list which is headed by the current object.
         If the object for which this function is invoked is a tile-component
         head, all instances for that tile-component have their attributes
         textualized. Similarly, if the object is a tile head, all
         tile-components for that tile have their attributes textualized and
         if the object is the cluster head, all objects in the cluster have
         their attributes textualized. Finally, if the object is the head of
         a list of clusters, all clusters will be textualized. */
    KDU_EXPORT void
      describe_strings(std::ostream &stream, bool include_comments=true);
      /* Print a text description of the attributes which are valid for
         the object.  If `include_comments' is true, descriptive comments
         will also be printed. */
    KDU_EXPORT void
      describe_string(const char *name, std::ostream &stream,
                      bool include_comments=true);
      /* Describes a single attribute. */
    KDU_EXPORT kdu_params *
      find_string(char *string, const char * &name);
      /* Finds the object which would be used by `parse_string' if parsing
         the supplied `string', returning a pointer to that object, if it
         exists.  Searches along lists following the same rules as
         `parse_string'.  Returns NULL if a match is not found.  Otherwise,
         the `name' argument is used to return the attribute name string
         (not decorated with tile- or component- specifiers). */
  protected: // Mostly for internal use by the base object.
    KDU_EXPORT void
      delete_unparsed_attribute(const char *name);
      /* Deletes the attribute with this name from the object.  Does the same
         for tile-components in any component list of which it is the head and
         also does the same for tiles in any tile list of which it is the
         head.  Generates an error if there is no attribute of this name. */
  // --------------------------------------------------------------------------
  public: // Marker oriented attribute access functions
    KDU_EXPORT bool
      translate_marker_segment(kdu_uint16 code, int num_bytes,
                               kdu_byte bytes[], int which_tile,
                               int tpart_idx);
      /* This function invokes the protected (and generally overridden)
         `read_marker_segment' member function of every object whose tile
         index agrees with `which_tile', until one is found which returns
         true. If no object can translate the marker segment, the function
         returns false. The marker code and the number of segment bytes are
         explicitly provided. The `bytes' array starts right after the segment
         length indicator and `num_bytes' indicates the length of this array,
         so `num_bytes' is always 2 bytes less than the length indicator in
         the actual code-stream marker segment.  The `tpart_idx' argument
         identifies the tile-part from which the marker segment originates.
         The first tile-part of each tile (and also the main header) has an
         index of 0. */
    KDU_EXPORT int
      generate_marker_segments(kdu_output *out, int which_tile, int tpart_idx);
      /* This function invokes the protected (and generally overridden)
         `write_marker_segment' member function of every object whose tile
         index agrees with `which_tile'. Marker segments are written starting
         from the tile head and working through each tile-component, for each
         cluster in the cluster list to which the current object belongs. The
         function returns the total number of bytes written, including the
         marker codes and segment bytes for all marker segments. If `out'
         is NULL, the process is only simulated -- nothing is written, but
         the return value represents the number of bytes which would be
         written out if `stream' had not been NULL.  The `tpart_idx'
         argument indicates the tile-part whose header is being written.  The
         first tile-part of each tile (and also the main header) have a
         tile-part index of 0. */
  protected: // Individual marker translators
    virtual int write_marker_segment(kdu_output *out, kdu_params *last_marked,
                                     int tpart_idx)
      { return 0; }
      /* This function should be overridden in any derived class which
         is capable of writing its contents into a code-stream marker segment.
         The function is called from within `generate_marker_segments', which
         also provides the `last_marked' pointer. This pointer may be safely
         cast to a pointer to the derived object. If not NULL, the function
         can determine whether or not there is a need to write a marker segment
         for this object by comparing the contents of the last marked object
         with those of the current object. If there is no difference, no marker
         segment need be written. In practice, `last_marked' is the most recent
         object in the current object's inheritance chain for which a marker
         segment was generated (return value not equal to zero). The function
         returns the total number of bytes occupied by the marker segment,
         including the marker code and the segment length field. If `stream'
         is NULL, the process is only simulated -- the length should be
         returned correctly, but nothing is actually written.  The `tpart_idx'
         field identifies the tile-part (starting from 0) into which the
         marker segment is being written. */
    virtual bool read_marker_segment(kdu_uint16 code, int num_bytes,
                                     kdu_byte bytes[], int tpart_idx)
      { return false; }
      /* This function should be overridden in any derived class which
         corresponds to a valid code-stream marker. The function is called
         from within the public `translate_marker_segment' method, which visits
         all relevant objects one by one until one of them is found whose
         `read_marker_segment' function returns true. The marker code is
         supplied, and the `bytes' array holds the data which follows the
         marker length field in the complete code-stream marker segment.
         `num_bytes' indicates the number of bytes in the `bytes' array.
         Thus, `num_bytes' is always 2 bytes less than the marker
         length field in the complete code-stream marker segment.  The function
         should always return false if the segment cannot be translated in
         the current object, even if the most appropriate object for the
         marker segment can be readily deduced.  Note that when a marker
         segment is translated by an object which supports multiple instances,
         a new instance will automatically be created to translate the
         contents of any future marker segments for the same tile-component.
         The `tpart_idx' field indicates the tile-part from whose header the
         marker segment is being read.  The first tile-part has an index
         of 0. */
  // --------------------------------------------------------------------------
  public: // Finalization functions
    virtual void finalize() {return; }
      /* This function is generally invoked through the `finalize_all'
         function described below.  Although it can usually be invoked
         quite safely when code-stream marker segments are used to recover
         attributes, it is intended primarily for use when attributes
         are derived by parsing text strings supplied as command line
         arguments.  Since the information provided in this manner is
         quite sparse, it is frequently necessary to fill in default
         values or convert summary quantities into a more complete
         set of attributes required for writing marker segments or performing
         compression. The function should be overridden in any derived
         class where such processing may be required. */
    KDU_EXPORT void
      finalize_all();
      /* This function invokes the `finalize' member function of the current
         object and every object in the list or lists headed by the current
         object.  If the object is a tile-component head, all instances
         are finalized. If the object is a tile head, all tile-components
         are finalized.  If the object is a cluster head, all objects in
         all tiles of the cluster are finalized.  If the object is the head
         of the list of clusters, all clusters are finalized.  For more
         information, see the definition of the `finalize' function itself. */
    KDU_EXPORT void
      finalize_all(int tile_idx);
      /* Same as above, but only those objects whose tile index agrees with
         the supplied argument are actually finalized.  This is useful when
         information becomes available on a tile-by-tile basis. */
  // --------------------------------------------------------------------------
  protected: // Data shared with derived classes
    const char *cluster_name; // Identitifies the derived class type.
    int tile_idx, comp_idx, inst_idx; // Object coordinates within cluster
  // --------------------------------------------------------------------------
  private: // Data
    bool allow_tiles, allow_comps, allow_insts;
    kdu_params *first_cluster, *next_cluster; /* Links clusters to one another.
                          Links are valid only for the first object in each
                          cluster (cluster heads). Otherwise, they are NULL. */
    kdu_params *first_tile, *next_tile; /* Links tiles within a cluster.
                          Links are only valid for the first object in each
                          tile (tile heads) and are otherwise NULL. */
    kdu_params *first_comp, *next_comp; /* Links components within a tile.
                          Links are only valid for the first object in each
                          component (tile-component heads) and are
                          otherwise NULL. */
    kdu_params *first_inst, *next_inst; /* Links instances of the same
                          tile-component. */
    int num_comps; /* Number of non-initial tile-components in current tile
                      list. Valid only for the head of an instance list. */
    kd_attribute *attributes; /* Points to a list of attributes. */
    friend struct kd_attribute;
    bool empty; // True until the first attempt to set any attribute records.
    bool marked; /* Becomes true when the contents of this object
                    are written to an explicit code-stream marker. */
  };

/*****************************************************************************/
/*                                   siz_params                              */
/*****************************************************************************/