CxImage reference

invalid-file

CxImage Class Members & Operations

• Constructors
• Initialization
• File
• Generic
• DSP
• Painting
• Multiple Images
• Transparency
• Palette
• Pixels
  
• Region Selection
• Alpha Channel
• Layers
• Attributes
• Miscellaneous
  

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 1
#define CXIMAGE_SUPPORT_JPG 1
#define CXIMAGE_SUPPORT_PNG 1
#define CXIMAGE_SUPPORT_MNG 0
#define CXIMAGE_SUPPORT_ICO 1
#define CXIMAGE_SUPPORT_TIF 1
#define CXIMAGE_SUPPORT_TGA 1
#define CXIMAGE_SUPPORT_PCX 1
#define CXIMAGE_SUPPORT_WBMP 1
#define CXIMAGE_SUPPORT_WMF 1
#define CXIMAGE_SUPPORT_J2K 0
#define CXIMAGE_SUPPORT_JBG 0
#define CXIMAGE_SUPPORT_JP2 1
#define CXIMAGE_SUPPORT_JPC 1
#define CXIMAGE_SUPPORT_PGX 1
#define CXIMAGE_SUPPORT_PNM 1
#define CXIMAGE_SUPPORT_RAS 1
Remember to rebuild the library if you change these statements.

Construction

CxImage(DWORD imagetype=0)	Creates an empty image. imagetype (optional) sets the image format.
CxImage(DWORD dwWidth, DWORD dwHeight, DWORD wBpp, DWORD imagetype=0)	Creates an image with the specified width, height, bit per pixel and (optional) image type arguments.
CxImage(const CxImage &isrc, bool copypixels=true, bool copyselection=true, bool copyalpha=true)	Creates an image with the same characteristics of the source image.
CxImage(const TCHAR * filename, DWORD imagetype) CxImage(FILE * stream, DWORD imagetype) CxImage(CxFile * stream, DWORD imagetype) CxImage(BYTE * buffer, DWORD size, DWORD imagetype)	Creates an image from file or memory. imagetype can be one of these formats: CXIMAGE_FORMAT_JPG, CXIMAGE_FORMAT_TIF, CXIMAGE_FORMAT_MNG, CXIMAGE_FORMAT_BMP, CXIMAGE_FORMAT_ICO, CXIMAGE_FORMAT_GIF, CXIMAGE_FORMAT_PNG, CXIMAGE_FORMAT_PCX, CXIMAGE_FORMAT_TGA, CXIMAGE_FORMAT_WMF, CXIMAGE_FORMAT_JBG, CXIMAGE_FORMAT_J2K, CXIMAGE_FORMAT_JP2, CXIMAGE_FORMAT_JPC, CXIMAGE_FORMAT_PGX, CXIMAGE_FORMAT_PNM, CXIMAGE_FORMAT_RAS, CXIMAGE_FORMAT_WBMP For automatic image type detection use CXIMAGE_FORMAT_UNKNOWN

Initialization

void* Create(DWORD dwWidth, DWORD dwHeight, DWORD wBpp, DWORD imagetype=0)	Initializes or rebuilds the image. Returns the pointer to the internal pDib object.
void Clear(BYTE bval=0)	Sets the image bits to the specified value.
bool Destroy()	Releases the image buffers.
void Copy(const CxImage &src, bool copypixels = true, bool copyselection = true, bool copyalpha = true)	Copies the image from an exsisting one.
HANDLE CopyToHandle()	Copies the image to a global memory handle (clipboard operations)
bool CreateFromHBITMAP(HBITMAP hbmp, HPALETTE hpal=0) bool CreateFromHICON(HICON hico)	Creates an image from a bitmap or icon object. (resource)
bool CreateFromHANDLE(HANDLE hMem)	Creates an image from a global bitmap handle. (clipboard operations)
bool CreateFromArray(BYTE* pArray,DWORD dwWidth,DWORD dwHeight,DWORD dwBitsperpixel, DWORD dwBytesperline, bool bFlipImage); bool CreateFromMatrix(BYTE** ppMatrix,DWORD dwWidth,DWORD dwHeight,DWORD dwBitsperpixel, DWORD dwBytesperline, bool bFlipImage);	Creates an image from a generic buffer. dwBitsperpixel can be 1,4,8,24,32
bool Transfer(CxImage &from)	Transfers the image from an existing source image. The source become empty.

File operations

bool LoadResource(HRSRC hRes, DWORD imagetype, HMODULE hModule=NULL)	Loads an image from the application resources. hRes is the resource handle returned by FindResource().
bool Save(const TCHAR * filename,DWORD imagetype=0) bool Encode(FILE * hFile, DWORD imagetype) bool Encode(CxFile * hFile, DWORD imagetype) bool Encode(BYTE * &buffer, long &size, DWORD imagetype)	Saves to disk or memory the image in a specific format. (Note: buffer must be NULL, the function allocates and fill the memory, the application must free the buffer)
bool Load(const TCHAR * filename,DWORD imagetype=0) bool Decode(FILE * hFile, DWORD imagetype) bool Decode(CxFile * hFile, DWORD imagetype) bool Decode(BYTE * buffer, DWORD size, DWORD imagetype)	Reads from disk or memory the image in a specific format.
bool Encode(CxFile * hFile, CxImage ** pImages, int pagecount, DWORD imagetype); bool Encode(FILE *hFile, CxImage ** pImages, int pagecount, DWORD imagetype);	Saves to disk or memory pagecount images, referenced by an array of CxImage pointers. imagetype can be CXIMAGE_FORMAT_TIF or CXIMAGE_FORMAT_GIF

Image operations

bool IsValid()	Checks if the image is correctly initializated.
bool IsEnabled()	True if the image is enabled for painting.
void Enable(bool enable=true)	Enables/disables the image.
bool Flip()	Flips upside down the image.
bool Mirror()	Mirrors the image.
bool Rotate(float angle, CxImage* iDst = NULL) bool RotateLeft(CxImage* iDst = NULL) bool RotateRight(CxImage* iDst = NULL) bool Rotate180(CxImage* iDst = NULL)	Rotates the image. angle can be positive for clockwise rotation or negative for counter-clockwise rotation. If iDst is NULL, the resulting image replaces the original.
bool Negative()	Inverts the image colors.
bool GrayScale()	Converts the image colors to 8 bit gray scale.
bool Resample(long newx, long newy, int mode = 1, CxImage* iDst = NULL)	Resizes the image. mode can be 0 for slow (bilinear) method , 1 for fast (nearest pixel) method, or 2 for accurate (bicubic spline interpolation) method. The function is faster with 24 and 1 bpp images, slow for 4 bpp images and slowest for 8 bpp images.
bool DecreaseBpp(DWORD nbit, bool errordiffusion, RGBQUAD* ppal = 0)	Reduces the number of bits per pixel to nbit (1, 4 or 8). ppal points to a valid palette for the final image; if not supplied the function will use a standard palette. ppal is not necessary for reduction to 1 bpp.
bool IncreaseBpp(DWORD nbit)	Increases the number of bits per pixel of the image.
bool Dither(long method = 0)	Converts the image to B&W using the Floyd-Steinberg (method = 0) or Ordered-Dithering (method = 1) algorithms.
bool Crop(long left, long top, long right, long bottom, CxImage* iDst = NULL) bool Crop(const RECT& rect, CxImage* iDst = NULL) bool CropRotatedRectangle( long topx, long topy, long width, long height, float angle, CxImage* iDst = NULL);	Extracts the specified rectangle from the image. If iDst is NULL, the resulting image replaces the original.
bool CircleTransform(int type,long rmax=0,float Koeff=1.0f);	Perform circle_based transformations. type is for different transformations : - 0 for normal (proturberant) FishEye - 1 for reverse (concave) FishEye - 2 for Swirle - 3 for Cilinder mirror - 4 for bathroom
bool Expand(long left, long top, long right, long bottom, RGBQUAD canvascolor, CxImage* iDst = 0); bool Expand(long newx, long newy, RGBQUAD canvascolor, CxImage* iDst = 0);	Expands the borders.
bool Thumbnail(long newx, long newy, RGBQUAD canvascolor, CxImage* iDst = 0);	Resamples the image with the correct aspect ratio, and fills the borders.

DSP operations

bool Threshold(BYTE level)	Converts the image to B&W. level is the lightness threshold. The Mean() function can be used for calculating the optimal threshold.
bool SplitRGB(CxImage* r,CxImage* g,CxImage* b) bool SplitYUV(CxImage* y,CxImage* u,CxImage* v) bool SplitHSL(CxImage* h,CxImage* s,CxImage* l) bool SplitYIQ(CxImage* y,CxImage* i,CxImage* q) bool SplitXYZ(CxImage* x,CxImage* y,CxImage* z) bool SplitCMYK(CxImage* c,CxImage* m,CxImage* y,CxImage* k)	Extract various channels from the image. Each channel is an 8 bit grayscale image.
bool Colorize(BYTE hue, BYTE sat)	Replaces the original hue and saturation values with hue and sat.
bool Light(long brightness, long contrast=0)	Changes the brightness and the contrast of the image. level can be from -255 to 255, if level is negative, the image becomes dark. contrast can be from -100 to 100, the neutral value is 0.
float Mean()	Returns the mean lightness of the image. Useful with Threshold and Light
bool Erode(long Ksize=2)	Enhance the dark areas of the image. Ksize is the size of the kernel.
bool Dilate(long Ksize=2)	Enhance the light areas of the image. Ksize is the size of the kernel.
bool Filter(long* kernel, long Ksize, long Kfactor, long Koffset)	2D linear filter. kernel is the convolving matrix, in row format; Ksize is the size of the kernel. Kfactor is the normalization constant; Koffset is the bias. Example: the "soften" filter uses this kernel: 1 1 1 1 8 1 1 1 1 the function needs: kernel={1,1,1,1,8,1,1,1,1}; Ksize=3; Kfactor=16; Koffset=0;
void Mix(CxImage & imgsrc2, ImageOpType op, long lXOffset = 0, long lYOffset = 0) void MixFrom(CxImage & imagesrc2, long lXOffset, long lYOffset);	Blends two images. op can be : OpAdd, OpAnd, OpXor, OpOr, OpMask, OpSrcCopy, OpDstCopy, OpSub, OpSrcBlend
bool ShiftRGB(long r, long g, long b)	Adjusts separately the red, green, and blue values in the image.
bool Gamma(float gamma)	Adjusts the color balance of the image. gamma can be from 0.1 to 5.
bool Median(long Ksize = 3)	Adjusts the intensity of each pixel to the median intensity of its surrounding pixels.
bool Noise(long level)	Adds an uniform noise to the image, level can be from 0 to 255.
bool Skew(float xgain, float ygain, long xpivot, long ypivot)	image skewing, xgain and ygain can be from 0 to 1, xpivot and ypivot is the center of the transformation.
bool Jitter(long radius = 2)	Adds a random offset to each pixel in the image
long Histogram(long* red, long* green = 0, long* blue = 0, long* gray = 0, long colorspace = 0)	Build the istogram of the image. red, green, blue, gray are long[256] or NULL. colorspace can be: 0 = RGB, 1 = HSL, 2 = YUV, 3 = YIQ, 4 = XYZ. The function returns the maximum value stored in the red, green, blue, gray buffers.
HistogramStretch(long method = 0); HistogramEqualize(); HistogramNormalize(); HistogramRoot(); HistogramLog();	Histogram functions. methos for HistogramStretch are : 0 = luminance , 1 = linked channels , 2 = independent channels.
bool FFT2(CxImage* srcReal, CxImage* srcImag, CxImage* dstReal, CxImage* dstImag, long direction = 1, bool bForceFFT = true, bool bMagnitude = true)	Computes the bidimensional FFT or DFT of the image. If the dimensions of the image are a power of, 2 the FFT is performed automatically. If dstReal and/or dstImag are NULL, the resulting images replaces the original(s). direction: 1 = forward, -1 = inverse. bForceFFT: Resample the image to make the dimensions a power of 2. bMagnitude: the real part returns the magnitude, the imaginary part returns the phase. Note: with 8 bits there is a HUGE loss in the dynamics the function tries to keep an acceptable SNR, but 8bit = 48dB...
bool Combine(CxImage* r,CxImage* g,CxImage* b,CxImage* a, long colorspace = 0)	Combines different color components, "a" can be NULL, the source colorspace can be: 0 = RGB, 1 = HSL, 2 = YUV, 3 = YIQ, 4 = XYZ
bool Repair(float radius = 0.25f, long niterations = 1, long colorspace = 0)	Smart blurring to remove small defects, dithering or artifacts.
bool UnsharpMask(float radius = 5.0, float amount = 0.5, int threshold = 0);
bool Lut(BYTE* pLut); bool Lut(BYTE* pLutR, BYTE* pLutG, BYTE* pLutB, BYTE* pLutA = 0);	Apply a look up table to the image or for each channel. "pLut"s are BYTE[256]

Painting operations

long Draw(HDC pDC, long xoffset, long yoffset, long xsize = -1, long size = -1, RECT* pClipRect = 0) long Draw(HDC hdc, const RECT& rect, RECT* pClipRect = 0)	Draws the image in the specified device context, with support for alpha channel, alpha palette, transparency, opacity.
long Draw2(HDC pDC, long xoffset, long yoffset, long xsize = -1, long size = -1) long Draw2(HDC hdc, const RECT& rect)	Draws the image in the specified device context, using the "true mask" method (simple transparency)
long Stretch(HDC pDC,long xoffset,long yoffset,long xsize,long ysize, DWORD dwRop = SRCCOPY) long Stretch(HDC hdc, const RECT& rect, DWORD dwRop = SRCCOPY)	Stretch the image (obsolete, use Draw), still useful for printing operations.
long Tile(HDC pDC, RECT *rc)	Tiles the image to fill the specified rectangle.
long DrawString(HDC hdc, long x, long y, const TCHAR* text, RGBQUAD color, const TCHAR* font, long lSize=0, long lWeight=400, BYTE bItalic=0, BYTE bUnderline=0, bool bSetAlpha=false); long DrawStringEx(HDC hdc, long x, long y, CXTEXTINFO *pTextType, bool bSetAlpha=false );	Draws a string in the image.
long Blt(HDC pDC, long x=0, long y=0)	Only for WinCE.

Multiple Images operations

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

long GetNumFrames()	Returns the number of images in the file. This function must be used after a Load() call. Use the sequence SetFrame(-1); Load(...); 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.

Transparency

long GetTransIndex()	Gets the index used for transparency. Returns -1 for no transparancy.
RGBQUAD GetTransColor()	Gets the color used for transparency.
void SetTransIndex(long idx)	Sets the index used for transparency with 1, 4 and 8 bpp images. Set to -1 to remove the effect.
void SetTransColor(RGBQUAD rgb)	Sets the color used for transparency with 24 bpp images. You must call SetTransIndex(0) to enable the effect, SetTransIndex(-1) to disable it.
bool IsTransparent()

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 GetPaletteColor(BYTE idx) bool GetPaletteColor(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)	Sets the palette entries.
void SetPaletteColor(BYTE idx, BYTE r, BYTE g, BYTE b) void SetPaletteColor(BYTE idx, RGBQUAD c) void SetPaletteColor(BYTE idx, COLORREF cr)	Sets the color of the specified palette index.
void SetGrayPalette()	Turns to gray scale palette.
void BlendPalette(COLORREF cr,long perc)	Colorize the palette.
bool IsGrayScale()	Returns true if the image has 256 colors and a linear grey scale palette.
bool IsIndexed()	Returns true if the image has 256 colors or less.
void SwapIndex(BYTE idx1, BYTE idx2)	Swaps two indexes in the image and their colors in the palette.
void SetStdPalette()	Sets a palette with standard colors for 4 and 8 bpp images.
void HuePalette(float correction=1)	Generates a "rainbow" palette with saturated colors. correction=1 generates a single hue spectrum. correction=0.75 is nice for scientific applications.
RGBQUAD HSLtoRGB(COLORREF cHSLColor) RGBQUAD RGBtoRGBQUAD(COLORREF cr) COLORREF RGBQUADtoRGB (RGBQUAD c) RGBQUAD RGBtoHSL(RGBQUAD lRGBColor) RGBQUAD HSLtoRGB(RGBQUAD lHSLColor) RGBQUAD YUVtoRGB(RGBQUAD lYUVColor) RGBQUAD RGBtoYUV(RGBQUAD lRGBColor) RGBQUAD YIQtoRGB(RGBQUAD lYIQColor); RGBQUAD RGBtoYIQ(RGBQUAD lRGBColor); RGBQUAD XYZtoRGB(RGBQUAD lXYZColor); RGBQUAD RGBtoXYZ(RGBQUAD lRGBColor); RGBtoBGR(BYTE *buffer, int length); RGB2GRAY(r,g,b)	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, bool bGetAlpha = true)	Returns the pixel color.
BYTE GetPixelGray(long x,long y)	Returns the pixel lightness
void SetPixelIndex(long x,long y,BYTE i)	Sets the pixel index, only for indexed images.
void SetPixelColor(long x,long y,RGBQUAD c, bool bSetAlpha = false) void SetPixelColor(long x,long y,COLORREF cr)	Sets the pixel color.
void DrawLine(int StartX, int EndX, int StartY, int EndY, RGBQUAD color, bool bSetAlpha=false); void DrawLine(int StartX, int EndX, int StartY, int EndY, COLORREF cr)

Region selection

bool SelectionCreate()	Allocates an empty selection.
bool SelectionDelete()	Deallocates the selction.
bool SelectionClear()	Empties the selection.
bool SelectionCopy(CxImage &from)	Imports an existing region from another image with the same width and height.
bool SelectionInvert()	Inverts the selection.
bool SelectionAddPixel(int x, int y)	Adds a single pixel to the existing selection.
bool SelectionAddRect(RECT r)	Adds a rectangle to the existing selection.
bool SelectionAddEllipse(RECT r)	Adds an ellipse to the existing selection.
bool SelectionAddPolygon(POINT *points, long npoints)	Adds a polygonal region to the existing selection. points points to an array of POINT structures. Each structure specifies the x-coordinate and y-coordinate of one vertex of the polygon. npoints specifies the number of POINT structures in the array pointed to by points.
void SelectionGetBox(RECT& r)	Gets the smallest rectangle that contains the selection
bool SelectionIsInside(long x, long y)	Checks if the coordinates are inside the selection.
bool SelectionAddColor(RGBQUAD c)	Adds to the selection all the pixels matching the specified color.
bool SelectionToHRGN(HRGN& region)	Converts the selection in a HRGN object.
bool SelectionIsValid()	Checks if the image has a valid selection.

Alpha channel

void AlphaCreate()	Allocates an empty (transparent) alpha channel.
void AlphaDelete()	Deallocates the alpha channel.
void AlphaClear()	Resets the alpha channel.
void AlphaInvert()	Inverts the alpha channel.
bool AlphaMirror()	Mirrors the alpha channel.
bool AlphaFlip()	Flips the alpha channel.
bool AlphaCopy(CxImage &from)	Imports an existing alpa channel from another image with the same width and height.
void AlphaStrip()	Blends the alpha channel and the alpha palette with the pixels. The result is a 24 bit image. The background color can be selected using SetTransColor().
bool AlphaSplit(CxImage *dest)	Exports the alpha channel in a 8bpp grayscale image.
void AlphaSet(BYTE level) void AlphaSet(long x,long y,BYTE level)	Sets the alpha level for the whole image or for a single pixel
void AlphaSet(CxImage &from)	Creates the alpha channel from a gray scale image
BYTE AlphaGet(long x,long y)	Returns the alpha level for the specified pixel.
BYTE AlphaGetMax() / void AlphaSetMax(BYTE nAlphaMax)	Get/Set global Alpha (opacity) value applied to the whole image.
bool AlphaIsValid()	Checks if the image has a valid alpha channel.
void AlphaPaletteClear()	Resets the alpha palette.
void AlphaPaletteEnable(bool enable=true)	Enables the alpha palette, so the Draw() function changes its behavior.
bool AlphaPaletteIsEnabled()	True if the alpha palette is enabled for painting.
bool AlphaPaletteSplit(CxImage *dest)	Exports the alpha channel in a 8bpp grayscale image.
bool AlphaPaletteIsValid()	Checks if the image has a valid alpha palette.
BYTE* AlphaGetBits()	Returns the pointer to the alpha layer (USE CAREFULLY)

Layers

bool LayerCreate(long position = -1)	Creates an empty layer. If position is less than 0, the new layer will be placed in the last position
bool LayerDelete(long position = -1)	Deletes a layer. If position is less than 0, the last layer will be deleted
void LayerDeleteAll()
CxImage* GetLayer(long position)	Returns a pointer to a layer. If position is less than 0, the last layer will be returned
CxImage* GetParent()	If the object is an internal layer, GetParent return its parent in the hierarchy.
long GetNumLayers()	Number of layers allocated directly by the object.

Attributes

long GetSize()	Returns the size in byte of the internal hDib object.
BYTE* GetBits(DWORD row)	Returns the pointer to the image pixels (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 GetType()	Returns the file extension associated with the image.
LPSTR GetLastError()	Returns the last reported error.
void* GetDIB()	Returns the internal hDib object.
BYTE GetJpegQuality() / void SetJpegQuality(BYTE q)	Image quality for JPEG and TIFF formats.
long GetXDPI() / void SetXDPI(long dpi) long GetYDPI() / void SetYDPI(long dpi)	Resolution for TIFF, JPEG, PNG and BMP formats.
DWORD GetCodecOption() void SetCodecOption(DWORD opt)	Encode option for GIF, TIF and JPG. GIF : 0 = RLE (default), 1 = none, 2 = LZW. TIF : 0 = automatic (default), or a valid compression code as defined in "tiff.h" (COMPRESSION_NONE = 1, COMPRESSION_CCITTRLE = 2, ...) JPG : valid values stored in enum CODEC_OPTION ( ENCODE_BASELINE = 0x01, ENCODE_PROGRESSIVE = 0x10, ...)
DWORD GetFlags() SetFlags(DWORD flags, bool bLockReservedFlags = true)	Image flags, for future use 0x??00000 = reserved for 16 bit, CMYK, multilayer 0x00??0000 = blend modes 0x0000???? = layer id or user flags bLockReservedFlags protects the "reserved" and "blend modes" flags
BYTE GetJpegScale() void SetJpegScale(BYTE q)	used for scaling down during JPEG decoding, valid numbers are 1, 2, 4, 8
void GetOffset(long *x,long *y) void SetOffset(long x,long y)	Image offset.

Miscellaneous

HBITMAP MakeBitmap(HDC hdc)	Creates a device-dependent bitmap (DDB) from the image (DIB). If hdc is NULL, the function returns a DIB.
long GetProgress()	Used to monitor the slow loops. The returned value is from 0 to 100.
long GetEscape()	Returns the escape code.
void SetProgress(long p)	Forces the value of the internal progress variable.
void SetEscape(long i)	Used to quit the slow loops or the codecs.
const TCHAR* GetVersion()