jp2.h

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

      /* Offsets and normalizes the original information for the indicated
         palette component, writing the result to the supplied `lut' array.
         The `comp_idx' value must be in the range 0 to `num_components'-1,
         where `num_components' is the value returned by `get_num_components'.
         The `lut' array must contain at least as many entries as the value
         returned by `get_num_entries'.  The `lut' entries are filled out as
         signed quantities in the range -0.5 to 0.5. */
    void get_lut(int comp_idx, kdu_sample16 lut[]);
      /* As above, except the lut holds the signed, normalized quantites
         in a 16-bit fixed point format, having KDU_FIX_POINT fraction bits.
         Again, the range of the quantities represented using this format is
         -0.5 to 0.5.  The selection of this representation is intended to
         facilitate interaction with the sample data processing operations
         conducted by the objects defined in "kdu_sample_processing.h". */
  // --------------------------------------------------------------------------
  private: // Embedded state
    j2_palette *state;
  };

/*****************************************************************************/
/*                              jp2_channels                                 */
/*****************************************************************************/

  /* Note: Objects of this class are merely interfaces to an internal
     implementation object, `j2_channels', which cannot be directly
     created by an application.  Creation and destruction of the internal
     object, as well as saving and reading of JP2 boxes are capabilities
     reserved for the internal machinery. Amongst other things, this
     protects the user against the possibility of losing control of
     resources when error conditions throw exceptions. */

class jp2_channels {
  public: // Lifecycle member functions
    jp2_channels()
      { state = NULL; }
    jp2_channels(j2_channels *state)
      { this->state = state; }
    bool operator!()
      { return (state == NULL); }
    bool exists()
      { return (state != NULL); }
  // --------------------------------------------------------------------------
  public: // Initialization member functions
    void init(int num_colours);
      /* Initializes the internal channels object with the indicated number
         of colour channels.  It is illegal to call this function unless
         there is an internal object (`exists' must return true) and that
         object has not yet been initialized.  In practice, this happens only
         when setting up a `jp2_target' object to construct a JP2 file.
         Note that the number of colour components must be either 1
         (luminance) or 3 (RGB). */
    void set_colour_mapping(int colour_idx, int codestream_component,
                            int palette_component=-1);
    void set_opacity_mapping(int colour_idx, int codestream_component,
                             int palette_component=-1);
    void set_premult_mapping(int colour_idx, int codestream_component,
                             int palette_component=-1);
       /* These functions are used to establish the relationship (if any)
          between the code-stream image components and the functions, colour,
          opacity and pre-multiplied opacity, for each colour channel.
          The `colour_idx' must lie in the range 0 through `num_colours'-1.
          A value of 0 refers to the red or luminance channel, while values
          of 1 and 2 refer to the green and blue channels, respectively.  A
          complete object must have a mapping for every colour, but need not
          necessarily have a mapping for opacity or pre-multiplied opacity
          functions. When first initialized, a `jp2_channels' object has
          mappings only for colour values and these identify the first three
          colour channels with the corresponding first three code-stream
          image components.
             The `codestream_component' argument must identify the image
          component (in the range 0 through `num_components'-1) which is used
          to create the relevant channel values.  The `palette_component'
          should be equal to -1 if the code-stream image component is used
          directly; otherwise, it identifies the zero-based index of the
          component (i.e., the lookup table) in a `jp2_palette' object,
          which operates on the code-stream image component samples.
             It should be noted that a codestream image component which is
          used as an index to a palette lookup table is not allowed to be
          used directly (i.e., it is only allowed to be used to index
          palette lookup tables).  Also, you must not use the same
          combination of source image component and palette lookup table
          (if any) for different types of reproduction functions (colour,
          opacity or pre-multiplied opacity).  You may, however, use the
          same image component or the same combination of image component
          and palette lookup table for multiple colour channels, multiple
          opacity channels or multiple pre-multiplied opacity channels. */
  // --------------------------------------------------------------------------
  public: // Access member functions
    int get_num_colours();
      /* Returns 1 for monochrome imagery and 3 for colour imagery. */
    bool get_colour_mapping(int colour_idx, int &codestream_component,
                            int &palette_component);
    bool get_opacity_mapping(int colour_idx, int &codestream_component,
                             int &palette_component);
    bool get_premult_mapping(int colour_idx, int &codestream_component,
                             int &palette_component);
       /* These functions are used to determine the relationship (if any)
          between the code-stream image components and the colour, opacity
          and pre-multiplied opacity values for each colour channel.
          The `colour_idx' must lie in the range 0 through `num_colours'-1.
          A value of 0 refers to the red or luminance channel, while values
          of 1 and 2 refer to the green and blue channels, respectively.
          Each function returns true if the relevant colour, opacity or
          pre-multpiplied opacity values exist.  It returns false if they do
          not exist.  The first function must return true for all legal
          `colour_idx' values, since every colour channel must at least
          have sample values.
             The `codestream_component' argument is used to return the
          index (starting from 0) of the code-stream image component
          which is used to create the relevant channel values.  The
          `palette_component' value will be set to -1 if the code-stream
          image component samples are to be used directly.  Otherwise, it
          will be set to the index of the component (i.e., the lookup table)
          in a `jp2_palette' object, which operates on the code-stream
          samples to produce the relevant channel values. */
  // --------------------------------------------------------------------------
  private: // Data
    j2_channels *state;
  };

/*****************************************************************************/
/*                            jp2_colour_space                               */
/*****************************************************************************/

enum jp2_colour_space {
    JP2_sLUM_SPACE,   // The standard luminance space (same gamma as sRGB)
    JP2_sRGB_SPACE,   // The standard RGB space
    JP2_sYCC_SPACE,   // YCC derivative of sRGB -- currently an ammendment
    JP2_iccLUM_SPACE, // Monochrome space described by an embedded ICC profile
    JP2_iccRGB_SPACE  /* 3-colour space described by an embedded ICC profile
                         Note that the 3 channels nominally represent some
                         type of RGB space, but just about any 3 component
                         non-opponent, device independent representation may
                         be involved. */
  };

/*****************************************************************************/
/*                               jp2_colour                                  */
/*****************************************************************************/

  /* Note: Objects of this class are merely interfaces to an internal
     implementation object, `j2_colour', which cannot be directly
     created by an application.  Creation and destruction of the internal
     object, as well as saving and reading of JP2 boxes are capabilities
     reserved for the internal machinery. Amongst other things, this
     protects the user against the possibility of losing control of
     resources when error conditions throw exceptions. */

class jp2_colour {
  public: // Lifecycle member functions
    jp2_colour()
      { state = NULL; }
    jp2_colour(j2_colour *state)
      { this->state = state; }
    bool operator!()
      { return (state == NULL); }
    bool exists()
      { return (state != NULL); }
  // --------------------------------------------------------------------------
  public: // Initialization member functions
    void init(jp2_colour_space space);
      /* Initializes the internal colour object with the indicated colour
         space description. It is illegal to call this function unless
         there is an internal object (`exists' must return true) and that
         object has not yet been initialized.  In practice, this happens only
         when setting up a `jp2_target' object to construct a JP2 file.
         Note that the `space' here must be one of JP2_sLUM_SPACE,
         JP2_sRGB_SPACE or JP2_sYCC_SPACE.  See below for spaces defined by
         an ICC profile. */
    void init(kdu_byte *icc_profile);
      /* Same as above, but the colour space is defined by an embedded ICC
         profile, contained in the supplied buffer.  The internal object
         makes a copy of this buffer.  The standard ICC header
         in this buffer identifies its length and other attributes.  The
         profile must identify a matrixed 3-colour input space, defined
         with respect to the XYZ Profile Connection Space (PCS_XYZ).  Apart
         from these requirements, the integrity of the profile may not be
         thoroughly checked. */
    void init(float gamma, float beta=0.0F, int num_points=100);
    void init(float matrix3x3[],
              float gamma, float beta=0.0F, int num_points=100);
      /* Same as above, but an embedded ICC profile is automatically
         generated to describe a luminance space (first form) or
         RGB space (second form) having the indicated gamma function
         and primary matrix (second form).
            The most commonly used form of the gamma function is not
         a pure power lay, but may be described by two parameters,
         gamma and beta, as explained in Chapter 1 of the book by
         Taubman and Marcellin.  For reference, the sRGB space has
         `gamma'=2.4 and `beta'=0.055, while the NTSC RGB space
         has `gamma'=2.2 and `beta'=0.099.  If `beta'=0, the gamma
         function is a pure power law and can be efficiently
         represented by the ICC profile.  Unfortunately, this
         form is not recommended, since inversion is ill conditioned
         and can substantially amplify quantization artifacts.  For
         the more general and more useful case where beta is non-zero,
         the function must be represented through tabulated values.
         These are uniformly spaced in the non-linear (gamma corrected)
         space.  The number of tabulated points may be explicitly
         controlled using the `num_points' argument.  Note that the
         function does not currently accept gamma values less than 1.
            The columns of the `matrix3x3' matrix hold the
         tri-stimulus responses (synthesized to achieve the desired
         appearance under the CIE D50 illuminant) associated with
         the linear (after undoing any gamma correction associated
         with the numerical channel values) colour channels.  The
         first column holds XYZ values for the linearized first (red)
         channel.  The second column holds XYZ values for the
         linearized second (green) channel.   The third column holds
         XYZ values for the linearized third (blue) channel.  The
         first row of the matrix holds X values; the second holds Y
         values; and the third holds Z values. */
  // --------------------------------------------------------------------------
  public: // Access member functions
    int get_num_colours();
      /* Returns 3 for RGB imagery and 1 for monochrome imagery.  Note that
         this is the same value returned by `jp2_channels::get_num_colours'. */
    jp2_colour_space get_space();
      /* If the return value is JP2_iccLUM_SPACE or JP2_iccRGB_SPACE, the
         colour space is defined by an embedded ICC profile; further
         information may be obtained as described below. */
    kdu_byte *get_icc_profile(int *num_bytes=NULL);
      /* Returns a pointer to a block of memory which holds the embedded
         ICC profile.  Returns NULL if the colour specification does not
         involve an embedded ICC profile.  Note that the block of memory
         belongs to the internal object; no attempt should be made to
         delete it or to use it beyond the lifetime of the object.  If
         `num_bytes' is non-NULL, the length of the profile is returned
         in *`num_bytes'. */
    bool get_icc_lut(int channel_idx, float lut[], int index_bits);
    bool get_icc_matrix(float matrix3x3[]);
      /* These functions are used to recover the ICC profile information
         which is actually usable by a conformant JP2 reader.  The standard
         suggests that JP2 readers should ignore everything else.  The