Introduction

CxImage is a C++ class to manage virtually any kind of images. It can load, save, display, transform images in a very simple and fast way.

Why another image library?

Around there are many good libraries (OpenIL, FreeImage, PaintLib ...), these are powerful, complete, and constantly updated. However if you ever try to use them, you may find some difficulties; because these libraries are mainly platform independent, written in C, somewhere with a basic C++ wrapper and with tons of compiler switch declarations.

Is it a MFC library?

No. Altogether it's a windows library, because of some particular constructors and the painting functions, but the backbone is platform independent.

To GIF or not to GIF?

Easy: PNG and MNG! The library contains LZW encoders/decoders. Due to Unisys patent enforcement, you should be aware of the limitations. The TIFF library is also affected by this. With CxImage it's a simple operation to remove a specific format, you are free to make your choice.

Hey, this library is huge!

I'm sorry, but each JPG, PNG and TIFF library adds about 100KB to the final application. CxImage impact is less than 50KB. So you should support and link only the formats that your application really needs.

History and credits.

Starting form my CxDib class, that implements memory DIBs only, I tried to add some members to read images from files. Looking for a solution,I found a nice MFC class named CImage on the net, release 1.4 (1998). CImage supports BMP, GIF, PNG and JPG, but suffers many little bugs and uses a complex class structure, so I decided to strip it to the base and merge CxDib with the CImage philosophy, to obtain the new CxImage class. Also I updated the libraries for JPG, PNG and ZLIB.

With CxImage is very easy to add new image types, so I added the TIFF library (rev. 6) and a minimal support for ICONs. Finally I added some specific constructors to obtain an image from global HANDLEs (windows clipboard) and objects (windows resources).

CImage is: (c)1995-1998, Alejandro Aguilar Sierra <asierra@servidor.unam.mx>
IJG JPEG library is: (c)1994-1998, Thomas G. Lane.
LibPNG version 1.0.12 is: (c)1998-2001 Glenn Randers-Pehrson
LibTIFF is: (c)1988-1997 Sam Leffler, (c)1991-1997 Silicon Graphics, Inc.
FreeImage 2.4.0 : Design and implementation by Floris van den Berg (flvdberg@wxs.nl)

More specific credits and disclaimers are in every header file of each library.

How to compile the library

You must compile all the libraries before you can compile the demo application. The whole operation is quite simple: open the CxImgLib.dsw workspace, select the menu "Build/Batch Build..." and click the "Build" button.

This will need some minutes to complete (the intermediate files occupy 60MB!). When everything is done, select the demo project and launch the application.
The demo application shows how to:

Open, save an display images.
Display Bitmap, Jpeg, Png or Gif resource.
Exchange images with the clipboard
Get pixels information
Transform the images

CxImage Class Members & Operations

Supported file formats

At the begining of the main header file ximage.h you'll find the definitions to enable or disable a specific format:
// CxImage supported formats #define CXIMAGE_SUPPORT_BMP 1 #define CXIMAGE_SUPPORT_GIF 0 #define CXIMAGE_SUPPORT_JPG 1 #define CXIMAGE_SUPPORT_PNG 1 #define CXIMAGE_SUPPORT_MNG 0 #define CXIMAGE_SUPPORT_ICO 1 #define CXIMAGE_SUPPORT_TIF 1Remember to rebuild the library if you change these statements.

Construction

`CxImage()`	- Creates an empty image.
`CxImage(DWORD dwWidth, DWORD dwHeight, WORD wBpp)`	- Creates an image with the specified width, height and bit per pixel arguments
`CxImage(const CxImage *isrc)`	- Creates an image with the same characteristics of the source image. The source image bits are not copied in the new image.
`CxImage(HBITMAP hbmp)`	- Creates an image from a bitmap object. (resource)
`CxImage(HANDLE hMem)`	- Creates an image from a global handle. (clipboard operations)
`CxImage(const char * filename, DWORD imagetype=0)`	- Creates an image from file

Initialization

`void* Create(DWORD dwWidth, DWORD dwHeight, WORD wBpp)`	- Initializes or rebuilds the image. Returns the pointer to the internal hDib object
`void Clear(BYTE bval=0)`	- Sets the image bits to the specified value.
`void Copy(CxImage *src)`	- Copies the image from an exsisting one.

Generic operations

`HANDLE CopyToHandle(HANDLE hMem)`	- Copies the image to a global memory handle (clipboard operations)
`bool LoadResource(HRSRC hRes, DWORD imagetype)`	- Loads an image from the application resources. `hRes` is the resource handle returned by `FindResource()`. `imagetype` can be one of these formats: CXIMAGE_FORMAT_JPG, CXIMAGE_FORMAT_ICO, CXIMAGE_FORMAT_GIF, CXIMAGE_FORMAT_PNG.
`void Transfer(CxImage *from)`	- Transfers the image from an existing source image. The source become empty.
`bool SaveFile(const char * filename, DWORD imagetype=0)`	- Saves to disk the image in a specific format
`bool ReadFile(const char * filename, DWORD imagetype=0)`	- Reads from disk the image in a specific format

Image operations

`bool IsValid()`	- Checks if the image is correctly initializated.
`bool Flip()`	- Flips upside down the image
`bool Mirror()`	- Mirrors the image
`bool GrayScale();`	- Convert the image colors to gray
`bool Rotate(float angle);`	- Rotates the image
`bool Negative()`	- Inverts the image colors

Painting operations

`long Draw(HDC pDC, long xoffset, long yoffset)`	- Draws the image in the specified device context and offsets
`long Stretch(HDC pDC,long xoffset,long yoffset,long xsize,long ysize)`	- Stretch the image
`long Tile(HDC pDC, RECT *rc)`	- Tiles the image to fill the specified rectangle

Multiple Images operations

These are specific function to load multiple TIFF and ICON images.

`long GetNumFrames()`	- Returns the number of images in the file. This function must be used after a `ReadFile()` call. Use the sequence `SetFrame(-1); ReadFile(...); GetNumFrames();` to get the number of images without loading the first image.
`long GetFrame()`	- Returns the current selected image (zero-based index)
`long SetFrame()`	- Set the image number that the next `ReadFile()` call will load.

Palette operations

These functions have no effects on RGB images and in this case the returned value is always 0.

`DWORD GetPaletteSize()`	- Returns the palette dimension in bytes
`RGBQUAD* GetPalette()`	- Returns the pointer to the first palette index
`RGBQUAD GetPaletteIndex(BYTE idx) bool GetRGB(int i, BYTE* r, BYTE* g, BYTE* b)`	- Returns the color of the specified index
`BYTE GetNearestIndex(RGBQUAD c)`	- Returns the best palette index that matches a specified color
`void SetPalette(DWORD n, BYTE r, BYTE g, BYTE b)` `void SetPalette(RGBQUAD pPal,DWORD nColors=256)` `void SetPalette(rgb_color_struct *rgb,DWORD nColors=256)`	- Set the palette entries.
`void SetPaletteIndex(BYTE idx, BYTE r, BYTE g, BYTE b)` `void SetPaletteIndex(BYTE idx, RGBQUAD c)` `void SetPaletteIndex(BYTE idx, COLORREF cr)`	- Set the color of the specified palette index
`void SetGrayPalette()`	- Turns to gray scale palette
`void BlendPalette(COLORREF cr,long perc)`	- Colorize the palette
`RGBQUAD HSLtoRGB(COLORREF cHSLColor)` `RGBQUAD RGB2RGBQUAD(COLORREF cr)` `COLORREF RGBQUAD2RGB (RGBQUAD c)` `RGBQUAD RGBtoHSL(RGBQUAD lRGBColor)` `RGBQUAD HSLtoRGB(RGBQUAD lHSLColor)`	- Color transformation utilities.

Pixels operations

`bool IsInside(long x, long y)`	- Checks if the coordinates are inside the image.
`BYTE GetPixelIndex(long x,long y)`	- Returns the pixel index (0 for RGB images)
`RGBQUAD GetPixelColor(long x,long y)`	- Returns the pixel color.
`void SetPixelIndex(long x,long y,BYTE i)`	- Sets the pixel index, only for indexed images
`void SetPixelColor(long x,long y,RGBQUAD c)` `void SetPixelColor(long x,long y,COLORREF cr)`	- Sets the pixel color.

Attributes

`long GetSize()`	- Returns the size in byte of the internal hDib object
`BYTE* GetBits()`	- Returns the pointer to the image bits (USE CAREFULLY)
`DWORD GetHeight()`
`DWORD GetWidth()`
`DWORD GetEffWidth()`	- Returns the DWORD aligned width of the image
`DWORD GetNumColors()`	- Returns 2, 16, 256; 0 for RGB images
`BYTE GetColorType()`	- Returns: 1=Palette, 2=RGB, 4=Alpha
`WORD GetBpp()`	- Returns: 1, 4, 8, 24.
`DWORD GetFileType()`	- Returns the file extension associated with the image
`LPSTR GetFilename()`	- Returns the file name associated with the image
`LPSTR GetLastError()`	- Returns the last reported error.

Remarks

The RLE decoder for bitmaps is actually not implemented. See PaintLib for a complete BMP encoder/decoder
The TIFF decoder for JPEG images generated by WANG Imaging for Windows (aka OJPEG support) will not be implemented. The reasons can be found in the LibTIFF site. The code to support this format is at ftp://ftp.remotesensing.org/libtiff/tiff-v3.5.7-alpha4.tar.gz

To do

Transparency
Rectangular and region selection.
Layers and frames.
Image filters (smooth, gradient, special effects)

Release History

v1.00 - 12 Aug 2001
- Basic implementation and interface.
v1.01 - 27 Aug 2001
- Fixed PNG read/save bugs, changed GIF read implementation.
- Fixed Mirror() function bug. New GrayScale() and Rotate() functions.
- Added LoadResource() function.
- Added multiple TIFF and ICON support

Compatibility

Win95,WinNT, Win98, WinME, W2K, WinXP = Yes

For any questions, e-mail to: ing.davide.pizzolato@libero.it