kdu_params.h

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

         constructor. */
    KDU_EXPORT void
      copy_from(kdu_params *source, int source_tile, int target_tile,
                int instance=-1, int skip_components=0,
                int discard_levels=0, bool transpose=false,
                bool vflip=false, bool hflip=false);
      /* This is a very powerful function, which may be very useful in
         implementing transcoding operations.  In the simplest case, the
         function copies the attributes of the `source' object into the
         current object, generating an error if they do not belong to exactly
         the same derived class.
            Copying will not occur unless the source and current objects'
         tile indices agree with the `source_tile' and `target_tile' arguments,
         respectively.  If both objects are the heads of their respective
         instance lists, all instances are visited until one is found which
         agrees with `instance', creating new instances for the target object
         if necessary.  If `instance' is -1, all instances are
         copied from the source.  If one or both objects is not the head of
         its instance list, at most that one object will be copied and then
         only if agreement can be reached with the value of the `instance'
         argument.
            When the source and/or target object is the head of a list of
         tile-components for some tile, all corresponding components are
         copied, skipping over the first `skip_components' components of
         the source list (but not the target list).  When the source and/or
         target object is the head of a list of tiles for some parameter
         cluster, the function automatically locates the tiles which match
         the `source_tile' and `target_tile' arguments before attempting a
         copy.  Finally, and most usefully, when either or both objects is
         the head of a list of parameter clusters, all corresponding clusters
         are visited and copied in accordance with the rules outlined above.
            Note carefully that no `kdu_params' object will be copied if the
         object has already had any record of any of its attributes set by
         any means.  In this event, the object is skipped, but an attempt is
         still made to copy any other objects in the relevant lists, following
         the rules outlined above.  The intent is to copy source objects into
         newly constructed (and hence empty) objects; however, the fact that
         individual objects will not be overwritten can come in handy when
         copying large parameter groupings, only some of which have already
         been set.
            The actual copying operation is performed by the internal function,
         "copy_with_xforms", which is overridden by each derived class.
         It is supplied the last 4 arguments, which may modify the data as it
         is being copied. */
  protected: // Specific transcoding members implemented by each derived class
    virtual void copy_with_xforms(kdu_params *source, int skip_components,
                                  int discard_levels, bool transpose,
                                  bool vflip, bool hflip) = 0;
      /* Each derived class must implement this pure virtual copy function.
         It may fail with an error message if any of the requested
         transformations cannot be implemented.
            The `skip_components' argument indicates the number of initial
         image components which are being discarded in a transcoding operation.
         This may impact some of the parameter attribute values.
            The `discard_levels' argument indicates the number of DWT
         decomposition levels which are being discarded in a transcoding
         operation to produce a reduced resolution version of the image.
            If `vflip' is true, the target representation should
         be a vertically flipped version of the source representation.
         If `hflip' is true, the target representation should be a
         horizontally flipped version of the source.  If `transpose' is true,
         the source representation is tranposed.  When `transpose' is used
         together with `vflip', the interpretation is that the top-most row
         in the target representation should be equivalent to the right-most
         column in the source representation.  That is, we think of first
         tranposing the source representation and then flipping it afterwards.
         The same principle applies for combinations of `transpose' and
         `hflip'.  That is, the left-most target column should be equivalent
         to the bottom-most source row. */
  // --------------------------------------------------------------------------
  public: // Navigation and identification member functions
    const char *identify_cluster()
      { return cluster_name; }
    KDU_EXPORT kdu_params *
      access_cluster(const char *cluster_name);
    KDU_EXPORT kdu_params *
      access_cluster(int sequence_idx);
      /* Locate a particular cluster, either by its name, or by its position
         in the underlying cluster list. The first cluster has
         `sequence_idx'=0 and may also be retrieved by supplying a NULL
         `cluster_name' argument.  Relevant `cluster_name' strings are defined
         with the derived class definitions, `siz_params', `cod_params', etc.,
         which appear toward the end of this file. */
    int get_instance()
      { return inst_idx; }
    int get_num_comps()
      { assert(first_inst->num_comps > 0); return first_inst->num_comps; }
      /* Fails if current object does not belong to a list of tile-components.
         Otherwise, returns the number of components (objects with non-negative
         component indices) in the list. */
    KDU_EXPORT kdu_params *
      access_relation(int tile_idx, int comp_idx, int inst_idx=0);
      /* Locate a particular object within the same cluster. If the object
         does not exist, the function returns NULL. */
  // --------------------------------------------------------------------------
  protected: // Assistance in constructing derived parameter classes
    KDU_EXPORT void
      define_attribute(const char *name, const char *comment,
                       const char *pattern, int flags=0);
      /* This function is called by the derived class's initializer to
         define all recognized attributes for the relevant class.
         `name' points to a string which may be used for textualizing
         the attribute. Relevant attribute names are defined with the derived
         classes toward the end of this file. `comment' provides a textual
         description of the attribute which may be used in generating usage
         statements. Valid `flags' are as follows: MULTI_RECORD means that
         multiple records are allowed; CAN_EXTRAPOLATE means that records
         can be accessed beyond those which have been actually written, with
         the missing elements extrapolated from those which are available;
         ALL_COMPONENTS means that this attribute does not have a
         component-specific form and may only be set in an object whose
         component index is -1. `pattern' identifies the structure of each
         field. The string contains a concatenation of any or all of the
         following:
            * "F" -- a floating point field
            * "I" -- an integer field
            * "B" -- a boolean field (textualized as "yes/no")
            * "(<string1>=<val>,<string2>=<val>,...)" -- an integer field,
              translated from one of the strings in the comma separated list
              of string/value pairs. Translation is case-sensitive.
            * "(<string1>=<val>|<string2>=<val>|...)" -- as above, but multiple
              strings, sparated by "|" symbols, may be translated and their
              values OR'd together to form the integer value. This is useful
              for building flag words. */
    static const int MULTI_RECORD;
    static const int CAN_EXTRAPOLATE;
    static const int ALL_COMPONENTS;
  // --------------------------------------------------------------------------
  public: // Binary attribute access functions
    KDU_EXPORT bool
      get(const char *name, int record_idx, int field_idx, int &value,
          bool allow_inherit=true, bool allow_extend=true,
          bool allow_derived=true);
    KDU_EXPORT bool
      get(const char *name, int record_idx, int field_idx, bool &value,
          bool allow_inherit=true, bool allow_extend=true,
          bool allow_derived=true); // Bools may also be retrieved as ints
    KDU_EXPORT bool
      get(const char *name, int record_idx, int field_idx, float &value,
          bool allow_inherit=true, bool allow_extend=true,
          bool allow_derived=true);
      /* The attribute `name' string is one of the names defined for the
         various derived classes, `siz_params', `cod_params', etc., appearing
         toward the end of this file.  Full string matching is not performed.
         The function generates an error if the request is incompatible with
         the record structure defined for this attribute. Returns false if the
         requested value has not yet been set and it cannot be synthesized
         from information available within the cluster. Synthesis rules are
         rather involved and may be explicitly manipulated by supplying the
         final two arguments.
            If an attribute has insufficient records, the existing records may
         be extended (extrapolated) so long as the CAN_EXTRAPOLATE flag was
         supplied when the attribute was defined and the `allow_extend'
         argument is true. If the attribute is empty, values may be
         synthesized by appealing to the same record in another object in the
         cluster, so long as the `allow_inherit' argument is true. The
         function first tries to use a summary object from the same tile
         (component index = -1); it then tries to use a summary object from
         the same component (tile index = -1); finally, it tries to use a
         summary object for all tiles and components (component and tile
         indices both -1). These rules apply only for objects whose
         instance number is 0. Other instances cannot be synthesized from
         other objects in the cluster. If none of these mechanisms succeed,
         the function returns false.
            If the `allow_derived' argument is false, the function will
         ignore any attributes which have been marked as holding derived
         quantities via the `set_derived' member function.  This is useful
         when you want to inherit attributes from objects in the same
         cluster, bypassing any intermediate objects for which values
         might have been automatically derived (usually inside the
         `finalize' function). */
    bool compare(const char *name, int record_idx, int field_idx, int value)
      { int val;
        return (get(name,record_idx,field_idx,val) && (val==value)); }
    bool compare(const char *name, int record_idx, int field_idx, bool value)
      { bool val;
        return (get(name,record_idx,field_idx,val) && (val==value)); }
    bool compare(const char *name, int record_idx, int field_idx, float value)
      { float val;
        return (get(name,record_idx,field_idx,val) && (val==value)); }
      /* Convenience functions which return false unless the indicated
         field and record of the attribute identified by `name' exists and
         has the same value as the supplied `value' argument.  These
         functions greatly simplify marker segment writing. */
    KDU_EXPORT void
      set(const char *name, int record_idx, int field_idx, int value);
    KDU_EXPORT void
      set(const char *name, int record_idx, int field_idx, bool value);
    KDU_EXPORT void
      set(const char *name, int record_idx, int field_idx, double value);
      /* Attribute `name' strings are defined with the various derived classes,
         `siz_params', `cod_params', etc., appearing toward the end of this
         file.  The function generates an error if the request is no attribute
         of this name is defined for the object, or the call is incompatible
         with the record structure defined for this attribute.  The number of
         records available for the attribute grows as required.  Note that
         boolean values may be written using either of the first two forms of
         the function. */
    KDU_EXPORT void
      set_derived(const char *name);
      /* Marks the attribute identified by `name' as holding automatically
         derived data which might not be treated in the same way as
         original data.  In particular, derived attributes might be
         skipped when the inheritance chain used by the `get' member
         function.  Also, derived attributes might be skipped during
         textualization. */
  // --------------------------------------------------------------------------
  public: // String oriented attribute access functions
    KDU_EXPORT bool
      parse_string(char *string);
      /* Parses a single attribute from the supplied string. The string may
         not contain any white space of any form at all. An error message
         will generally be produced if this requirement is violated. The
         function examines the available attributes for one whose name
         matches the initial portion of the supplied string. The attribute
         name is delimited by an '=' or a ':' character (see below). If the
         match fails, the function proceeds to test successive clusters. If
         no match is found, the function returns false.
            Once a match is found, the function checks for an optional
         tile-component locator which consists of a ':' followed by either