// ----------------------------------------------------------
  
  class fipMemoryIO;
  class fipMultiPage;
  class fipTag;
  
  

A class used to manage all photo related images and all image types used by the library.

          fipImage encapsulates the FIBITMAP format. It relies on the FreeImage library, especially for 
          loading / saving images and for bit depth conversion.
  
	 version:  FreeImage 3
  
  
	 author:  Hervé Drolon
  
  */
  
  class FIP_API fipImage : public fipObject
  {
  protected:
  

DIB data FIBITMAP *_dib; TRUE whenever the display need to be refreshed mutable BOOL _bHasChanged;

  public:
          friend class fipMultiPage;
  
  public:
  
          

@name Creation & Destruction

  
          //@{        
          

Constructor
see: FreeImage_AllocateT

  
          fipImage(FREE_IMAGE_TYPE image_type = FIT_BITMAP, WORD width = 0, WORD height = 0, WORD bpp = 0);
  

Destructor ~fipImage();

Image allocator
see: FreeImage_AllocateT

        BOOL setSize(FREE_IMAGE_TYPE image_type, WORD width, WORD height, WORD bpp, unsigned red_mask = 0, unsigned green_mask = 0, unsigned blue_mask = 0);

Destroy image data virtual void clear(); //@}

@name Copying

        //@{        
        

Copy constructor
see: FreeImage_Clone

        fipImage(const fipImage& src);
        

Copy constructor
see: FreeImage_Clone

        fipImage& operator=(const fipImage& src);
        

<b>Assignement operator</b><br> Copy the input pointer and manage its destruction
see: operator FIBITMAP*()

        fipImage& operator=(FIBITMAP *dib);

        

@brief Copy a sub part of the current image and returns it as a fipImage object. This method works with any bitmap type.
parameter: dst Output subimage
parameter: left Specifies the left position of the cropped rectangle.
parameter: top Specifies the top position of the cropped rectangle.
parameter: right Specifies the right position of the cropped rectangle.
parameter: bottom Specifies the bottom position of the cropped rectangle.
returns: Returns TRUE if successful, FALSE otherwise.
see: FreeImage_Copy

        BOOL copySubImage(fipImage& dst, int left, int top, int right, int bottom) const;

        

@brief Alpha blend or combine a sub part image with the current image.

    The bit depth of dst bitmap must be greater than or equal to the bit depth of src. 
        Upper promotion of src is done internally. Supported bit depth equals to 4, 8, 16, 24 or 32.

	 parameter:  src Source subimage


	 parameter:  left Specifies the left position of the sub image. 


	 parameter:  top Specifies the top position of the sub image. 


	 parameter:  alpha Alpha blend factor. The source and destination images are alpha blended if 

        alpha = 0..255. If alpha > 255, then the source image is combined to the destination image.

	 returns:  Returns TRUE if successful, FALSE otherwise.


	 see:  FreeImage_Paste

	*/
        BOOL pasteSubImage(fipImage& src, int left, int top, int alpha = 256);

        

@brief Crop a sub part of the current image and update it accordingly. This method works with any bitmap type.
parameter: left Specifies the left position of the cropped rectangle.
parameter: top Specifies the top position of the cropped rectangle.
parameter: right Specifies the right position of the cropped rectangle.
parameter: bottom Specifies the bottom position of the cropped rectangle.
returns: Returns TRUE if successful, FALSE otherwise.

        BOOL crop(int left, int top, int right, int bottom);

        //@}

        

@name Loading & Saving Loading and saving is handled by the FreeImage library.

        //@{        
        

@brief Loads an image from disk, given its file name and an optional flag.
parameter: lpszPathName Path and file name of the image to load.
parameter: flag The signification of this flag depends on the image to be read.
returns: Returns TRUE if successful, FALSE otherwise.
see: FreeImage_Load, FreeImage documentation

        BOOL load(const char* lpszPathName, int flag = 0);

        

UNICODE version of load (this function only works under WIN32 and does nothing on other OS)
see: load

        BOOL loadU(const wchar_t* lpszPathName, int flag = 0);

        

@brief Loads an image using the specified FreeImageIO struct and fi_handle, and an optional flag.
parameter: io FreeImageIO structure
parameter: handle FreeImage fi_handle
parameter: flag The signification of this flag depends on the image to be read.
returns: Returns TRUE if successful, FALSE otherwise.
see: FreeImage_LoadFromHandle, FreeImage documentation

        BOOL loadFromHandle(FreeImageIO *io, fi_handle handle, int flag = 0);

        

@brief Loads an image using the specified memory stream and an optional flag.
parameter: memIO FreeImage memory stream
parameter: flag The signification of this flag depends on the image to be read.
returns: Returns TRUE if successful, FALSE otherwise.
see: FreeImage_LoadFromMemory, FreeImage documentation

        BOOL loadFromMemory(fipMemoryIO& memIO, int flag = 0);

        

@brief Saves an image to disk, given its file name and an optional flag.
parameter: lpszPathName Path and file name of the image to save.
parameter: flag The signification of this flag depends on the image to be saved.
returns: Returns TRUE if successful, FALSE otherwise.
see: FreeImage_Save, FreeImage documentation

        BOOL save(const char* lpszPathName, int flag = 0) const;

        

UNICODE version of save (this function only works under WIN32 and does nothing on other OS)
see: save

        BOOL saveU(const wchar_t* lpszPathName, int flag = 0) const;

        

@brief Saves an image using the specified FreeImageIO struct and fi_handle, and an optional flag.
parameter: fif Format identifier (FreeImage format)
parameter: io FreeImageIO structure
parameter: handle FreeImage fi_handle
parameter: flag The signification of this flag depends on the image to be saved.
returns: Returns TRUE if successful, FALSE otherwise.
see: FreeImage_SaveToHandle, FreeImage documentation

        BOOL saveToHandle(FREE_IMAGE_FORMAT fif, FreeImageIO *io, fi_handle handle, int flag = 0) const;

        

@brief Saves an image using the specified memory stream and an optional flag.
parameter: fif Format identifier (FreeImage format)
parameter: memIO FreeImage memory stream
parameter: flag The signification of this flag depends on the image to be saved.
returns: Returns TRUE if successful, FALSE otherwise.
see: FreeImage_SaveToMemory, FreeImage documentation

        BOOL saveToMemory(FREE_IMAGE_FORMAT fif, fipMemoryIO& memIO, int flag = 0) const;

        //@}

        

@name Information functions Accessors to the DIB BITMAPINFO structure.

        //@{        

        

Returns the data type of the image
see: FreeImage_GetImageType

        FREE_IMAGE_TYPE getImageType() const;

        

Returns the image width in pixels
see: FreeImage_GetWidth

        WORD getWidth() const;
        
        

Returns the image height in pixels
see: FreeImage_GetHeight

        WORD getHeight() const;
        
        

Returns the width of the bitmap in bytes rounded to the nearest DWORD.
see: FreeImage_GetPitch

        WORD getScanWidth() const;

        

Returns a pointer to the FIBITMAP data. Used for direct access from FREEIMAGE functions or from your own low level C functions.<br> <b>Sample use</b> : <br> <pre> fipImage src, dst; src.load("test.png"); dst = FreeImage_ConvertTo8Bits(src); FreeImage_Save(FIF_TIFF, dst, "test.tif", 0); </pre>
see: operator=(FIBITMAP *dib)

        operator FIBITMAP*() { 
                return _dib; 
        }

Returns TRUE if the image is allocated, FALSE otherwise BOOL isValid() const;

Returns a pointer to the bitmap's BITMAPINFO header.
see: FreeImage_GetInfo

        BITMAPINFO* getInfo() const;

        

Returns a pointer to the bitmap's BITMAPINFOHEADER.
see: FreeImage_GetInfoHeader

    BITMAPINFOHEADER* getInfoHeader() const;

        

Returns the size of the bitmap in bytes. The size of the bitmap is the BITMAPINFOHEADER + the size of the palette + the size of the bitmap data.
see: FreeImage_GetDIBSize

        LONG getImageSize() const;
        
        

Returns the bitdepth of the bitmap. <br> When the image type is FIT_BITMAP, valid bitdepth can be 1, 4, 8, 16, 24 or 32.
see: FreeImage_GetBPP, getImageType

        WORD getBitsPerPixel() const;

        

Returns the width of the bitmap in bytes.<br> <b>This is not the size of the scanline</b>.
see: FreeImage_GetLine, getScanWidth

        WORD getLine() const;

        

Returns the bitmap resolution along the X axis, in pixels / cm
see: FreeImage_GetDotsPerMeterX

        double getHorizontalResolution() const;
        
        

Returns the bitmap resolution along the Y axis, in pixels / cm
see: FreeImage_GetDotsPerMeterY

        double getVerticalResolution() const;

        

set the bitmap resolution along the X axis, in pixels / cm
see: FreeImage_GetInfoHeader

        void setHorizontalResolution(double value);
        
        

set the bitmap resolution along the Y axis, in pixels / cm
see: FreeImage_GetInfoHeader

        void setVerticalResolution(double value);

        //@}

        

@name Palette operations

        //@{
        

Returns a pointer to the bitmap's palette. If the bitmap doesn't have a palette, getPalette returns NULL.
see: FreeImage_GetPalette

        RGBQUAD* getPalette() const;
        
        

Returns the palette size in <b>bytes</b>.
see: FreeImage_GetColorsUsed

        WORD getPaletteSize() const;

        

Retrieves the number of colours used in the bitmap. If the bitmap is non-palletised, 0 is returned.
see: FreeImage_GetColorsUsed

        WORD getColorsUsed() const;

        

Investigates the colour type of the bitmap.
see: FreeImage_GetColorType, FREE_IMAGE_COLOR_TYPE

        FREE_IMAGE_COLOR_TYPE getColorType() const;

        

Returns TRUE if the bitmap is a 8-bit bitmap with a greyscale palette, FALSE otherwise
see: FreeImage_GetBPP, FreeImage_GetColorType

        BOOL isGrayscale() const;
        //@}

        

@name Pixel access

        //@{        

        

@brief Returns a pointer to the bitmap bits.

        It is up to you to interpret these bytes correctly, 
        according to the results of FreeImage_GetBPP and 
        GetRedMask, FreeImage_GetGreenMask and FreeImage_GetBlueMask.<br>
        Use this function with getScanWidth to iterates through the pixels. 

	 see:  FreeImage_GetBits

	*/
        BYTE* accessPixels() const;

        

@brief Returns a pointer to the start of the given scanline in the bitmap’s data-bits. This pointer can be cast according to the result returned by getImageType.<br> Use this function with getScanWidth to iterates through the pixels.
see: FreeImage_GetScanLine, FreeImage documentation

        BYTE* getScanLine(WORD scanline) const;

        

Get the pixel index of a 1-, 4- or 8-bit palettized image at position (x, y), including range check (slow access).
parameter: x Pixel position in horizontal direction
parameter: y Pixel position in vertical direction
parameter: value Pixel index (returned value)
returns: Returns TRUE if successfull, FALSE otherwise.
see: FreeImage_GetPixelIndex

        BOOL getPixelIndex(unsigned x, unsigned y, BYTE *value) const;

        

Get the pixel color of a 16-, 24- or 32-bit image at position (x, y), including range check (slow access).
parameter: x Pixel position in horizontal direction
parameter: y Pixel position in vertical direction
parameter: value Pixel color (returned value)
returns: Returns TRUE if successfull, FALSE otherwise.
see: FreeImage_GetPixelColor

        BOOL getPixelColor(unsigned x, unsigned y, RGBQUAD *value) const;

        

Set the pixel index of a 1-, 4- or 8-bit palettized image at position (x, y), including range check (slow access).
parameter: x Pixel position in horizontal direction
parameter: y Pixel position in vertical direction
parameter: value Pixel index
returns: Returns TRUE if successfull, FALSE otherwise.
see: FreeImage_SetPixelIndex

        BOOL setPixelIndex(unsigned x, unsigned y, BYTE *value);

        

Set the pixel color of a 16-, 24- or 32-bit image at position (x, y), including range check (slow access).
parameter: x Pixel position in horizontal direction
parameter: y Pixel position in vertical direction
parameter: value Pixel color
returns: Returns TRUE if successfull, FALSE otherwise.
see: FreeImage_SetPixelColor

        BOOL setPixelColor(unsigned x, unsigned y, RGBQUAD *value);

        //@}

        

@name Conversion routines Bitmaps are always loaded in their default bit depth. If you want the bitmap to be stored in another bit depth, the class provides several conversion functions.

        //@{        
        

Converts an image to a type supported by FreeImage.
parameter: image_type New image type
parameter: scale_linear TRUE if image pixels must be scaled linearly when converting to a standard bitmap
returns: Returns TRUE if successfull, FALSE otherwise.
see: FreeImage_ConvertToType, FreeImage_ConvertToStandardType

        BOOL convertToType(FREE_IMAGE_TYPE image_type, BOOL scale_linear = TRUE);

        

Converts the bitmap to 1 bit using a threshold T.
parameter: T Threshold value in [0..255]
returns: Returns TRUE if successfull, FALSE otherwise.
see: FreeImage_Threshold

        BOOL threshold(BYTE T);
        
        

Converts a 8-bit image to a monochrome 1-bit image using a dithering algorithm.
parameter: algorithm Dithering algorithm to use.
returns: Returns TRUE if successfull, FALSE otherwise.
see: FreeImage_Dither, FREE_IMAGE_DITHER

        BOOL dither(FREE_IMAGE_DITHER algorithm);

        

Converts the bitmap to 4 bits. Unless the bitmap is a 1-bit palettized bitmap, colour values are converted to greyscale.
returns: Returns TRUE if successfull, FALSE otherwise.
see: FreeImage_ConvertTo4Bits

        BOOL convertTo4Bits();

        

Converts the bitmap to 8 bits. If the bitmap is 24 or 32-bit RGB, the colour values are converted to greyscale.
returns: Returns TRUE if successfull, FALSE otherwise.
see: FreeImage_ConvertTo8Bits

        BOOL convertTo8Bits();

        

Converts the bitmap to 8 bits.<br> For palletized bitmaps, the color map is converted to a greyscale ramp.
see: FreeImage_ConvertToGreyscale
returns: Returns TRUE if successfull, FALSE otherwise.

        BOOL convertToGrayscale();
        
        

Quantizes a full colour 24-bit bitmap to a palletised 8-bit bitmap.<br> The quantize parameter specifies which colour reduction algorithm should be used.
parameter: algorithm Color quantization algorithm to use.
returns: Returns TRUE if successfull, FALSE otherwise.
see: FreeImage_ColorQuantize, FREE_IMAGE_QUANTIZE

        BOOL colorQuantize(FREE_IMAGE_QUANTIZE algorithm);

        

Converts the bitmap to 16 bits. The resulting bitmap has a layout of 5 bits red, 5 bits green, 5 bits blue and 1 unused bit.
returns: Returns TRUE if successfull, FALSE otherwise.
see: FreeImage_ConvertTo16Bits555

        BOOL convertTo16Bits555();
        
        

Converts the bitmap to 16 bits. The resulting bitmap has a layout of 5 bits red, 6 bits green and 5 bits blue.
returns: Returns TRUE if successfull, FALSE otherwise.
see: FreeImage_ConvertTo16Bits565

        BOOL convertTo16Bits565();
        
        

Converts the bitmap to 24 bits.
returns: Returns TRUE if successfull, FALSE otherwise.
see: FreeImage_ConvertTo24Bits

        BOOL convertTo24Bits();
        
        

Converts the bitmap to 32 bits.
returns: Returns TRUE if successfull, FALSE otherwise.
see: FreeImage_ConvertTo32Bits

        BOOL convertTo32Bits();

        

Converts the bitmap to a 96-bit RGBF image.
returns: Returns TRUE if successfull, FALSE otherwise.
see: FreeImage_ConvertToRGBF

        BOOL convertToRGBF();

        

Converts a High Dynamic Range image (48-bit RGB or 96-bit RGB Float) to a 24-bit RGB image.
parameter: tmo Tone mapping operator
parameter: first_param First tone mapping algorithm parameter (algorithm dependant)
parameter: second_param Second tone mapping algorithm parameter (algorithm dependant)
returns: Returns TRUE if successfull, FALSE otherwise.
see: FreeImage_ToneMapping

        BOOL toneMapping(FREE_IMAGE_TMO tmo, double first_param = 0, double second_param = 0);

        //@}

        

@name Transparency support: background colour and alpha channel

        //@{

        

Returns TRUE if the image is transparent, returns FALSE otherwise
see: FreeImage_IsTransparent

        BOOL isTransparent() const;

        

8-bit transparency : get the number of transparent colors.
returns: Returns the number of transparent colors in a palletised bitmap.
see: FreeImage_GetTransparencyCount

        unsigned getTransparencyCount() const;

        

8-bit transparency : get the bitmap’s transparency table.
returns: Returns a pointer to the bitmap’s transparency table.
see: FreeImage_GetTransparencyTable

        BYTE* getTransparencyTable() const;

        

8-bit transparency : set the bitmap’s transparency table.
see: FreeImage_SetTransparencyTable

        void setTransparencyTable(BYTE *table, int count);

        

Returns TRUE when the image has a file background color, FALSE otherwise.
see: FreeImage_HasBackgroundColor

        BOOL hasFileBkColor() const;

        

@brief Retrieves the file background color of an image. For 8-bit images, the color index in the palette is returned in the rgbReserved member of the bkcolor parameter.
returns: Returns TRUE if successful, FALSE otherwise.
see: FreeImage_GetBackgroundColor

        BOOL getFileBkColor(RGBQUAD *bkcolor) const;

        

@brief Set the file background color of an image. When saving an image to PNG, this background color is transparently saved to the PNG file. When the bkcolor parameter is NULL, the background color is removed from the image.
returns: Returns TRUE if successful, FALSE otherwise.
see: FreeImage_SetBackgroundColor

        BOOL setFileBkColor(RGBQUAD *bkcolor);
        //@}

        

@name Channel processing support

        //@{        
        

@brief Retrieves the red, green, blue or alpha channel of a 24- or 32-bit BGR[A] image.
parameter: image Output image to be extracted
parameter: channel Color channel to extract
returns: Returns TRUE if successful, FALSE otherwise.
see: FreeImage_GetChannel, FREE_IMAGE_COLOR_CHANNEL

        BOOL getChannel(fipImage& image, FREE_IMAGE_COLOR_CHANNEL channel) const;

        

@brief Insert a 8-bit dib into a 24- or 32-bit image.
parameter: image Input 8-bit image to insert
parameter: channel Color channel to replace
returns: Returns TRUE if successful, FALSE otherwise.
see: FreeImage_SetChannel, FREE_IMAGE_COLOR_CHANNEL

        BOOL setChannel(fipImage& image, FREE_IMAGE_COLOR_CHANNEL channel);

        

@brief Split a 24-bit RGB image into 3 greyscale images corresponding to the red, green and blue channels.
parameter: RedChannel Output red channel.
parameter: GreenChannel Output green channel.
parameter: BlueChannel Output blue channel.
returns: Returns FALSE if the dib isn't a valid image, if it's not a 24-bit image or if one of the output channel can't be allocated. Returns TRUE otherwise.
see: FreeImage_GetChannel

        BOOL splitChannels(fipImage& RedChannel, fipImage& GreenChannel, fipImage& BlueChannel);

        

@brief Builds a 24-bit RGB image given its red, green and blue channel.
parameter: red Input red channel.
parameter: green Input green channel.
parameter: blue Input blue channel.
returns: Returns FALSE if the dib can't be allocated, if the input channels are not 8-bit images. Returns TRUE otherwise.
see: FreeImage_SetChannel

        BOOL combineChannels(fipImage& red, fipImage& green, fipImage& blue);
        //@}

        

@name Rotation and flipping

        //@{        
        

Image translation and rotation using B-Splines.
parameter: angle Image rotation angle, in degree
parameter: x_shift Image horizontal shift
parameter: y_shift Image vertical shift
parameter: x_origin Origin of the x-axis
parameter: y_origin Origin of the y-axis
parameter: use_mask Whether or not to mask the image. Image mirroring is applied when use_mask is set to FALSE
returns: Returns the translated & rotated dib if successful, returns NULL otherwise
see: FreeImage_RotateEx

        BOOL rotateEx(double angle, double x_shift, double y_shift, double x_origin, double y_origin, BOOL use_mask);

        

Image rotation by means of three shears.
parameter: angle Image rotation angle, in degree
returns: Returns rotated dib if successful, returns NULL otherwise
see: FreeImage_RotateClassic

        BOOL rotate(double angle);

        

Flip the image horizontally along the vertical axis
see: FreeImage_FlipHorizontal

        BOOL flipHorizontal();

        

Flip the image vertically along the horizontal axis
see: FreeImage_FlipVertical

        BOOL flipVertical();
        //@}

        

@name Color manipulation routines

        //@{        
        

Inverts each pixel data.
returns: Returns TRUE if successful, FALSE otherwise.
see: FreeImage_Invert

        BOOL invert();
        
        

@brief Perfoms an histogram transformation on a 8, 24 or 32-bit image according to the values of a lookup table (LUT).

        The transformation is done as follows.<br>
        Image 8-bit : if the image has a color palette, the LUT is applied to this palette, 
        otherwise, it is applied to the grey values.<br>
        Image 24-bit & 32-bit : if channel == IPL_CC_RGB, the same LUT is applied to each color
        plane (R,G, and B). Otherwise, the LUT is applied to the specified channel only.

	 parameter:  LUT Lookup table. The size of 'LUT' is assumed to be 256.


	 parameter:  channel The color channel to be processed (only used with 24 & 32-bit DIB).


	 returns:  Returns TRUE if the operation was successful, FALSE otherwise


	 see:  FreeImage_AdjustCurve, FREE_IMAGE_COLOR_CHANNEL

	*/
        BOOL adjustCurve(BYTE *LUT, FREE_IMAGE_COLOR_CHANNEL channel);

        

@brief Performs gamma correction on a 8, 24 or 32-bit image.
parameter: gamma Gamma value to use. A value of 1.0 leaves the image alone, less than one darkens it, and greater than one lightens it.
returns: Returns TRUE if the operation was successful, FALSE otherwise
see: FreeImage_AdjustGamma, adjustCurve

        BOOL adjustGamma(double gamma);

        

@brief Adjusts the brightness of a 8, 24 or 32-bit image by a certain amount.
parameter: percentage Where -100 <= percentage <= 100
A value 0 means no change, less than 0 will make the image darker and greater than 0 will make the image brighter.
returns: Returns TRUE if the operation was succesful, FALSE otherwise
see: FreeImage_AdjustBrightness, adjustCurve

        BOOL adjustBrightness(double percentage);

        

@brief Adjusts the contrast of a 8, 24 or 32-bit image by a certain amount.
parameter: percentage Where -100 <= percentage <= 100
A value 0 means no change, less than 0 will decrease the contrast and greater than 0 will increase the contrast of the image.
returns: Returns TRUE if the operation was succesfull, FALSE otherwise
see: FreeImage_AdjustContrast, adjustCurve

        BOOL adjustContrast(double percentage);

        

@brief Computes image histogram For 24-bit and 32-bit images, histogram can be computed from red, green, blue and black channels. For 8-bit images, histogram is computed from the black channel. Other bit depth is not supported.
parameter: histo pointer to an histogram array. Size of this array is assumed to be 256.
parameter: channel Color channel to use
returns: Returns TRUE if the operation was succesfull, FALSE otherwise
see: FreeImage_GetHistogram

        BOOL getHistogram(DWORD *histo, FREE_IMAGE_COLOR_CHANNEL channel = FICC_BLACK) const;
        //@}

        

@name Upsampling / downsampling

        //@{        

        

@brief Rescale the image to a new width / height.

	 parameter:  new_width New image width


	 parameter:  new_height New image height


	 parameter:  filter The filter parameter specifies which resampling filter should be used.


	 returns:  Returns TRUE if the operation was successful, FALSE otherwise


	 see:  FreeImage_Rescale, FREE_IMAGE_FILTER

	*/
        BOOL rescale(WORD new_width, WORD new_height, FREE_IMAGE_FILTER filter);

        

@brief Creates a thumbnail image keeping aspect ratio

	 parameter:  max_size Maximum width or height in pixel units


	 parameter:  convert When set to TRUE, converts the image to a standard type


	 returns:  Returns TRUE if the operation was successful, FALSE otherwise


	 see:  FreeImage_MakeThumbnail

	*/
        BOOL makeThumbnail(WORD max_size, BOOL convert = TRUE);
        //@}

        

@name Image status

        //@{        
        

Set the image status as 'modified'.<br> When using the fipWinImage class, the image status is used to refresh the display. It is changed to FALSE whenever the display has just been refreshed.
parameter: bStatus TRUE if the image should be marked as modified, FALSE otherwise
see: isModified

        void setModified(BOOL bStatus = TRUE) {
                _bHasChanged = bStatus;
        }

        

Get the image status
returns: Returns TRUE if the image is marked as modified, FALSE otherwise
see: setModified

        BOOL isModified() {
                return _bHasChanged;
        }
        //@}

        

@name Metadata

        //@{        
        

Returns the number of tags contained in the <i>model</i> metadata model attached to the dib
parameter: model Metadata model to look for

        unsigned getMetadataCount(FREE_IMAGE_MDMODEL model) const;
        

Retrieve a metadata attached to the dib
parameter: model Metadata model to look for
parameter: key Metadata field name
parameter: tag Returned tag
returns: Returns TRUE if the operation was succesfull, FALSE otherwise
see: FreeImage_GetMetadata

        BOOL getMetadata(FREE_IMAGE_MDMODEL model, const char *key, fipTag& tag) const;
        

Attach a new FreeImage tag to the dib
parameter: model Metadata model used to store the tag
parameter: key Tag field name
parameter: tag Tag to be attached
returns: Returns TRUE if the operation was succesfull, FALSE otherwise
see: FreeImage_SetMetadata

        BOOL setMetadata(FREE_IMAGE_MDMODEL model, const char *key, fipTag& tag);
        //@}

  protected:
        

@name Internal use

        //@{
          BOOL replace(FIBITMAP *new_dib);
        //@}

};

// ----------------------------------------------------------

A class designed for MS Windows (TM) platforms.

    fipWinImage provides methods used to :
        <ul>
        <li>Display a DIB on the screen
        <li>Copy / Paste a DIB to/from Windows devices (HANDLE, HBITMAP, Clipboard)
        <li>Capture a window (HWND) and convert it to an image
        </ul>

	 version:  FreeImage 3


	 author:  Hervé Drolon

*/
ifdef _WIN32

class FIP_API fipWinImage : public fipImage
{
public:
        

@name Creation & Destruction

        //@{        

Constructor fipWinImage(FREE_IMAGE_TYPE image_type = FIT_BITMAP, WORD width = 0, WORD height = 0, WORD bpp = 0);

Destructor ~fipWinImage();

Destroy image data virtual void clear();

Returns TRUE if the image is allocated, FALSE otherwise BOOL isValid() const; //@}

@name Copying

        //@{        

        

Copy constructor. Delete internal _display_dib data and copy the base class image data. Tone mapping parameters are left unchanged.
see: FreeImage_Clone

        fipWinImage& operator=(const fipImage& src);

        

Copy constructor Delete internal _display_dib data and copy tone mapping parameters. Copy also the base class image data.
see: FreeImage_Clone

        fipWinImage& operator=(const fipWinImage& src);

        

Clone function used for clipboard copy.<br> Convert the FIBITMAP image to a DIB, and transfer the DIB in a global bitmap handle.<br> For non standard bitmaps, the BITMAPINFOHEADER->biCompression field is set to 0xFF + FreeImage_GetImageType(_dib), in order to recognize the bitmap as non standard.

        HANDLE copyToHandle() const;

        

Copy constructor used for clipboard paste.<br> Converts a global object to a FIBITMAP. The clipboard format must be CF_DIB.<br> When the BITMAPINFOHEADER->biCompression field is set to 0xFF + [one of the predefined FREE_IMAGE_TYPE], the bitmap is recognized as non standard and correctly copied.
returns: Returns TRUE if successful, returns FALSE otherwise

        BOOL copyFromHandle(HANDLE hMem);

        

Copy constructor.<br> Converts a HBITMAP object to a FIBITMAP.
returns: Returns TRUE if successful, returns FALSE otherwise

        BOOL copyFromBitmap(HBITMAP hbmp);
        //@}

        

@name Clipboard operations

        //@{        
        

Clipboard copy.
parameter: hWndNewOwner Handle to the window to be associated with the open clipboard. In MFC, you can use AfxGetApp()->m_pMainWnd->GetSafeHwnd().
returns: Returns TRUE if successful, returns FALSE otherwise

        BOOL copyToClipboard(HWND hWndNewOwner) const;

        

Retrieves data from the clipboard. The clipboard format must be CF_DIB.
returns: Returns TRUE if successful, returns FALSE otherwise

        BOOL pasteFromClipboard();
        //@}

        

@name Screen capture

        //@{        
        

Capture a window and convert it to an image
parameter: hWndApplicationWindow Handle to the application main window
parameter: hWndSelectedWindow Handle to the window to be captured
returns: Returns TRUE if successful, returns FALSE otherwise

        BOOL captureWindow(HWND hWndApplicationWindow, HWND hWndSelectedWindow);
        //@}

        

@name Painting operations

        //@{        

        

@brief Draw (stretch) the image on a HDC, using StretchDIBits.

    When the image is transparent or has a file background, this function composite 
        the foreground image against a checkerboard background image.

	 parameter:  hDC Handle to the device context


	 parameter:  rcDest Destination rectangle


	 see:  FreeImage_Composite

	*/
        void draw(HDC hDC, RECT& rcDest) const {
                drawEx(hDC, rcDest, FALSE, NULL, NULL);
        }

        

@brief Draw (stretch) the image on a HDC, using StretchDIBits.

    When the image is transparent or has a file background, this function can composite 
        the foreground image against a checkerboard background image, against a single background color or 
        against a user background image.<br>
        When the image is a High Dynamic Range image (48-bit or RGB float), this function will apply a 
        tone mapping operator before drawing the image.<br>
        The original image (located in the fipImage class) will not be affected by any of the operations 
        that could be done in order to display it. 

	 parameter:  hDC Handle to the device context


	 parameter:  rcDest Destination rectangle


	 parameter:  useFileBkg When set to TRUE, the function uses the file color background if there is one


	 parameter:  appBkColor When a color is given, the function uses it as the background color


	 parameter:  bg When a FIBITMAP is given, the function uses it as the background image


	 see:  FreeImage_Composite


	 see:  setToneMappingOperator

	*/
        void drawEx(HDC hDC, RECT& rcDest, BOOL useFileBkg = FALSE, RGBQUAD *appBkColor = NULL, FIBITMAP *bg = NULL) const;

        

Select a tone mapping algorithm used for drawing and set the image as modified so that the display will be refreshed.
parameter: tmo Tone mapping operator
parameter: first_param First tone mapping algorithm parameter
parameter: second_param Second tone mapping algorithm parameter
see: FreeImage_ToneMapping

        void setToneMappingOperator(FREE_IMAGE_TMO tmo, double first_param = 0, double second_param = 0);

        

Get the tone mapping algorithm used for drawing, with its parameters.
parameter: tmo Tone mapping operator
parameter: first_param First tone mapping algorithm parameter
parameter: second_param Second tone mapping algorithm parameter
see: FreeImage_ToneMapping

        void getToneMappingOperator(FREE_IMAGE_TMO *tmo, double *first_param, double *second_param) const;

        //@}

protected:

DIB used for display (this allow to display non-standard bitmaps) mutable FIBITMAP *_display_dib; remember to delete _display_dib mutable BOOL _bDeleteMe; tone mapping operator FREE_IMAGE_TMO _tmo; first tone mapping algorithm parameter double _tmo_param_1; second tone mapping algorithm parameter double _tmo_param_2; };

endif // _WIN32

// ----------------------------------------------------------

Memory handle fipMemoryIO is a class that allows you to load / save images from / to a memory stream.
version: FreeImage 3
author: Hervé Drolon

class FIP_API fipMemoryIO : public fipObject
{
protected:

Pointer to a memory stream FIMEMORY *_hmem;

public :
        

Constructor. Wrap a memory buffer containing image data.<br> The memory buffer is read only and has to be freed by the user when no longer in use.<br> When default arguments are used, open a memory file as read/write.
parameter: data Pointer to the memory buffer
parameter: size_in_bytes Buffer size in bytes
see: FreeImage_OpenMemory

    fipMemoryIO(BYTE *data = NULL, DWORD size_in_bytes = 0);

        

Destructor. Free any allocated memory
see: FreeImage_CloseMemory

        ~fipMemoryIO();

        

Returns TRUE if the internal memory buffer is a valid buffer, returns FALSE otherwise

        BOOL isValid() const;

        

Returns the buffer image format
see: FreeImage_GetFileTypeFromMemory

        FREE_IMAGE_FORMAT getFileType() const;

        

Returns a pointer to the FIMEMORY data. Used for direct access from FREEIMAGE functions or from your own low level C functions.

        operator FIMEMORY*() { 
                return _hmem; 
        }

        

@name Memory IO routines

        //@{        
        

Loads a dib from a memory stream
parameter: fif Format identifier (FreeImage format)
parameter: flags The signification of this flag depends on the image to be loaded.
returns: Returns the loaded dib if successful, returns NULL otherwise
see: FreeImage_LoadFromMemory

        FIBITMAP* load(FREE_IMAGE_FORMAT fif, int flags = 0) const;
        

Saves a dib to a memory stream
parameter: fif Format identifier (FreeImage format)
parameter: dib Image to be saved
parameter: flags The signification of this flag depends on the image to be saved.
returns: Returns TRUE if successful, returns FALSE otherwise
see: FreeImage_SaveToMemory

        BOOL save(FREE_IMAGE_FORMAT fif, FIBITMAP *dib, int flags = 0);
        

Reads data from a memory stream
parameter: buffer Storage location for data
parameter: size Item size in bytes
parameter: count Maximum number of items to be read
returns: Returns the number of full items actually read, which may be less than count if an error occurs
see: FreeImage_ReadMemory

        unsigned read(void *buffer, unsigned size, unsigned count) const;
        

Writes data to a memory stream
parameter: buffer Pointer to data to be written
parameter: size Item size in bytes
parameter: count Maximum number of items to be written
returns: Returns the number of full items actually written, which may be less than count if an error occurs
see: FreeImage_WriteMemory

        unsigned write(const void *buffer, unsigned size, unsigned count);
        

Gets the current position of a memory pointer
see: FreeImage_TellMemory

        long tell() const;
        

Moves the memory pointer to a specified location
see: FreeImage_SeekMemory

        BOOL seek(long offset, int origin);
        

Provides a direct buffer access to a memory stream
parameter: data Pointer to the memory buffer (returned value)
parameter: size_in_bytes Buffer size in bytes (returned value)
see: FreeImage_AcquireMemory

        BOOL acquire(BYTE **data, DWORD *size_in_bytes);
        //@}

private:

Disable copy fipMemoryIO(const fipMemoryIO& src); Disable copy fipMemoryIO& operator=(const fipMemoryIO& src);

};

// ----------------------------------------------------------

Multi-page file stream

        fipMultiPage encapsulates the multi-page API. It supports reading/writing 
        multi-page TIFF, ICO and GIF files. 
*/
class FIP_API fipMultiPage : public fipObject 
{
protected:

Pointer to a multi-page file stream FIMULTIBITMAP *_mpage; TRUE when using a memory cache, FALSE otherwise BOOL _bMemoryCache;

public:
        

Constructor
parameter: keep_cache_in_memory When it is TRUE, all gathered bitmap data in the page manipulation process is kept in memory, otherwise it is lazily flushed to a temporary file on the hard disk in 64 Kb blocks.

        fipMultiPage(BOOL keep_cache_in_memory = FALSE);

        

Destructor Close the file stream if not already done.

        ~fipMultiPage();

Returns TRUE if the multi-page stream is opened BOOL isValid() const;

Open a file stream
parameter: lpszPathName Name of the multi-page bitmap file
parameter: create_new When TRUE, it means that a new bitmap will be created rather than an existing one being opened
parameter: read_only When TRUE the bitmap is opened read-only
parameter: flags Load flags. The signification of this flag depends on the image to be loaded.
returns: Returns TRUE if successful, returns FALSE otherwise
see: FreeImage_OpenMultiBitmap

        BOOL open(const char* lpszPathName, BOOL create_new, BOOL read_only, int flags = 0);

        

Open a multi-page memory stream as read only.
parameter: memIO Memory stream. The memory stream MUST BE a wrapped user buffer.
parameter: flags Load flags. The signification of this flag depends on the image to be loaded.
returns: Returns TRUE if successful, returns FALSE otherwise
see: FreeImage_LoadMultiBitmapFromMemory

        BOOL open(fipMemoryIO& memIO, int flags = 0);

        

Close a file stream
parameter: flags Save flags. The signification of this flag depends on the image to be saved.
returns: Returns TRUE if successful, returns FALSE otherwise
see: FreeImage_CloseMultiBitmap

        BOOL close(int flags = 0);

        

Returns the number of pages currently available in the multi-paged bitmap
see: FreeImage_GetPageCount

        int getPageCount() const;

        

Appends a new page to the end of the bitmap
parameter: image Image to append
see: FreeImage_AppendPage

        void appendPage(fipImage& image);

        

Inserts a new page before the given position in the bitmap
parameter: page Page number. Page has to be a number smaller than the current number of pages available in the bitmap.
parameter: image Image to insert
see: FreeImage_InsertPage

        void insertPage(int page, fipImage& image);

        

Deletes the page on the given position
parameter: page Page number
see: FreeImage_DeletePage

        void deletePage(int page);

        

Moves the source page to the position of the target page.
parameter: target Target page position
parameter: source Source page position
returns: Returns TRUE if successful, returns FALSE otherwise
see: FreeImage_MovePage

        BOOL movePage(int target, int source);

        

Locks a page in memory for editing. You must call unlockPage to free the page<br> <b>Usage : </b><br> <pre> fipMultiPage mpage; // ... fipImage image; // You must declare this before image = mpage.lockPage(2); if(image.isValid()) { // ... mpage.unlockPage(image, TRUE); } </pre>
parameter: page Page number
returns: Returns the page if successful, returns NULL otherwise
see: FreeImage_LockPage

        FIBITMAP* lockPage(int page);

        

Unlocks a previously locked page and gives it back to the multi-page engine
parameter: image Page to unlock
parameter: changed When TRUE, the page is marked changed and the new page data is applied in the multi-page bitmap.
see: FreeImage_UnlockPage

        void unlockPage(fipImage& image, BOOL changed);

        

Returns an array of page-numbers that are currently locked in memory. When the pages parameter is NULL, the size of the array is returned in the count variable. You can then allocate the array of the desired size and call getLockedPageNumbers again to populate the array.
returns: Returns TRUE if successful, returns FALSE otherwise
see: FreeImage_GetLockedPageNumbers

        BOOL getLockedPageNumbers(int *pages, int *count) const;
};

// ----------------------------------------------------------

FreeImage Tag

FreeImage uses this structure to store metadata information. 
*/
class FIP_API fipTag : public fipObject
{
protected:

Pointer to a FreeImage tag FITAG *_tag;

public:
        

@name Creation & Destruction

        //@{        
        

Constructor
see: FreeImage_CreateTag

        fipTag();
        

Destructor
see: FreeImage_DeleteTag

        ~fipTag();
        //@}

        

@name Copying

        //@{        
        

Copy constructor
see: FreeImage_CloneTag

        fipTag(const fipTag& tag);
        

Copy constructor
see: FreeImage_CloneTag

        fipTag& operator=(const fipTag& tag);
        

<b>Assignement operator</b><br> Copy the input pointer and manage its destruction
see: operator FITAG*()

        fipTag& operator=(FITAG *tag);
        //@}

        

Returns a pointer to the FITAG data. Used for direct access from FREEIMAGE functions or from your own low level C functions.
see: operator=(FITAG *tag)

        operator FITAG*() { 
                return _tag; 
        }

Returns TRUE if the tag is allocated, FALSE otherwise BOOL isValid() const;

@name Tag accessors

        //@{        
        

Returns the tag field name (unique inside a metadata model).
see: FreeImage_GetTagKey

        const char *getKey() const;
        

Returns the tag description if available, returns NULL otherwise
see: FreeImage_GetTagDescription

        const char *getDescription() const;
        

Returns the tag ID if available, returns 0 otherwise
see: FreeImage_GetTagID

        WORD getID() const;
        

Returns the tag data type
see: FreeImage_GetTagType

        FREE_IMAGE_MDTYPE getType() const;
        

Returns the number of components in the tag (in tag type units)
see: FreeImage_GetTagCount

        DWORD getCount() const;
        

Returns the length of the tag value in bytes
see: FreeImage_GetTagLength

        DWORD getLength() const;
        

Returns the tag value
see: FreeImage_GetTagValue

        const void *getValue() const;
        

Set the tag field name
returns: Returns TRUE if successful, returns FALSE otherwise
see: FreeImage_SetTagKey

        BOOL setKey(const char *key);
        

Set the (usually optional) tag description
returns: Returns TRUE if successful, returns FALSE otherwise
see: FreeImage_SetTagDescription

        BOOL setDescription(const char *description);
        

Set the (usually optional) tad ID
returns: Returns TRUE if successful, returns FALSE otherwise
see: FreeImage_SetTagID

        BOOL setID(WORD id);
        

Set the tag data type
returns: Returns TRUE if successful, returns FALSE otherwise
see: FreeImage_SetTagType

        BOOL setType(FREE_IMAGE_MDTYPE type);
        

Set the number of data in the tag
returns: Returns TRUE if successful, returns FALSE otherwise
see: FreeImage_SetTagCount

        BOOL setCount(DWORD count);
        

Set the length of the tag value, in bytes
returns: Returns TRUE if successful, returns FALSE otherwise
see: FreeImage_SetTagLength

        BOOL setLength(DWORD length);
        

Set the tag value
returns: Returns TRUE if successful, returns FALSE otherwise
see: FreeImage_SetTagValue

        BOOL setValue(const void *value);

        //@}

        

Converts a FreeImage tag structure to a string that represents the interpreted tag value
parameter: model Metadata model specification (metadata model from which the tag was extracted)
parameter: Make Camera model (not used yet)

        const char* toString(FREE_IMAGE_MDMODEL model, char *Make = NULL) const;

};

Metadata iterator

<b>Usage : </b><br>
<pre>
fipImage image;
// ...
fipTag tag;
fipMetadataFind finder;
if( finder.findFirstMetadata(FIMD_EXIF_MAIN, image, tag) ) {
  do {
    // process the tag
        cout << tag.getKey() << "\n";

  } while( finder.findNextMetadata(tag) );
}
// the class can be called again with another metadata model
if( finder.findFirstMetadata(FIMD_EXIF_EXIF, image, tag) ) {
  do {
    // process the tag
        cout << tag.getKey() << "\n";

  } while( finder.findNextMetadata(tag) );
}
</pre>
*/
class FIP_API fipMetadataFind : public fipObject
{
protected:

Pointer to a search handle FIMETADATA *_mdhandle;

public:

Returns TRUE if the search handle is allocated, FALSE otherwise BOOL isValid() const;

Constructor fipMetadataFind();

Destructor
see: FreeImage_FindCloseMetadata

  
          ~fipMetadataFind();
          

Provides information about the first instance of a tag that matches the metadata model specified in the <i>model</i> argument.
parameter: model Metadata model
parameter: image Input image
parameter: tag Returned tag
returns: Returns TRUE if successful, returns FALSE otherwise
see: FreeImage_FindFirstMetadata

  
          BOOL findFirstMetadata(FREE_IMAGE_MDMODEL model, fipImage& image, fipTag& tag);
          

Find the next tag, if any, that matches the metadata model argument in a previous call to findFirstMetadata
parameter: tag Returned tag
returns: Returns TRUE if successful, returns FALSE otherwise, indicating that no more matching tags could be found
see: FreeImage_FindNextMetadata

  
          BOOL findNextMetadata(fipTag& tag);
  
  };
  
  endif        // FREEIMAGEPLUS_H
  

---

[] readme course(s) preface I 1 2 II 3 4 III 5 6 7 IV 8 9 10 V 11 12 afterthought(s) appendix reference(s) example(s) resource(s) _

---

(C) Æliens 04/09/2009

You may not copy or print any of this material without explicit permission of the author or the publisher. In case of other copyright issues, contact the author.