Untitled Document

http://www.aoi.it Untitled Document

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 char * 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.
`void 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)
`void CreateFromHBITMAP(HBITMAP hbmp) void 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 CreateFromARGB(DWORD dwWidth,DWORD dwHeight,BYTE* argbArray)`	Creates an image from an ARGB buffer.
`void 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 char * filename,DWORD imagetype=0)` `bool Save(LPCWSTR 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 char * filename,DWORD imagetype=0)` `bool Load(LPCWSTR 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)`	Extracts the specified rectangle from the image. If `iDst` is NULL, the resulting image replaces the original.

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)`	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(); HistogramEqualize(); HistogramNormalize(); HistogramRoot(); HistogramLog();`	Histogram functions.
`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.

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)` `long Stretch(HDC hdc, const RECT& rect)`	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 DrawText(HDC hdc, long x, long y, const char* text, RGBQUAD color, const char* font, long lSize=0, long lWeight=400, BYTE bItalic=0, BYTE bUnderline=0)`	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 `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.

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)`	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 bEditAlpha = false)` `void SetPixelColor(long x,long y,COLORREF cr)`	Sets the pixel color.

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 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.

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()`	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 GetEncodeOption() void SetEncodeOption(DWORD opt)`	Encode option for GIF and TIF 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, ...)
`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
`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 char* GetVersion()`