ImgDrawFx - The Function

Let's take a close look at the ImgDrawImageFX function and get into some details. We start with the function declaration:

int IMAPI ImgDrawImageFX ( HANDLE hImage, HDC hDC, LPRECT pDstBound, LPRECT pSrcBounds, UINT nEffect, DWORD dwFlags, DWORD dwExtra, IMFXCALLBACK pfnCallback, UINT nInterval, DWORD dwUserInfo, HPALETTE hPal )

Given the parameters :

HANDLE hImage is the ImageMan handle to be drawn.

HANDLE hDC the device context handle where the drawing will occur.

pDstBounds and pSrcBounds are the destination and source RECTangle boundaries. Watch out when you are displaying an image using special effects. If the image is not displayed at its real size or scaled down to drawing size, it will get scaled at each step of the effect while it is drawing. This can make for some really bad, chunky and slow effects. You don't want that! If you pass NULL for pSrcBounds, the entire image will be drawn.

UINT nEffect specifies one of the 22 possible effects to use while drawing. The possible values are found in the imgman.h header in the enum tag_ImageManDrawEffects and all are named with the IMFX_ prefix.

DWORD dwFlags is a set of optional flags that modify the behavior of the effect's drawing process. The possible values for this parameter depends entirely on the nEffect chosen. These are also listed in the imgman.h header along with the effect enum list. The possible modifiers for each effect are grouped with that effect for easy reference. They are all named with the IMDF_ prefix. In general, they specify how the image to be drawn will effect an image that may already exist in the drawing area. For example, does the new image draw over the top of the existing image or does it push the existing one out while it's being drawn.

DWORD dwExtra is another parameter that modifies the drawing behavior. Its use is also dependent on the effect being used. See below for a more in depth look at this parameter.

IMFXCALLBACK pfnCallback specifies a callback function that ImageMan will periodically call during the actual drawing of the image. Pass NULL in this parameter if you don't want to use any callback. See the next section on Using the Special Effects Callback.

UINT nInterval specifies how often as a percentage the callback function, if one is being used, is called. The valid range is 0 - 100. Be careful specifying small values. For example, if you specify 0, your callback is called in between every single effect operation. It could take an extremely long time to display the image and unless you are using a callback, there will be no way to interrupt the draw.

DWORD dwUserInfo is what you supply that will be passed to the callback function. You can use this for such things as passing the file name of the image.

HPALETTE hPal is a handle to a palette that will be selected and realized for the effect. Currently, only the blur effect uses this parameter. In general, you should manage your own palette selection and realization.

The parameter dwExtra is used to control different magnitudes of each effect type that is drawn. In some cases it actually holds two values contained as this DWORD's high and low words. For example, when using the wipe effect, this parameter specifies the number of pixel to wipe during each operation. However, when using a mosaic the low word high word combination specifies the cell width and height respectively. Following is a quick run down on dwExtra's uses:

Effect Low/High usage

Wipe step increment / unused

Mosaic cell width / cell height (if height is 0, then it is the same as the width)

Creeping Mosaic cell width and height / fill percent

Curtain step increment / unused

Venetian Blinds step increment / slat size

Shape X increment / Y increment

Here is a short example of drawing an image in its full size using a Mosaic effect with cell width of 5 and cell height of 10:

RECT rect ;

DWORD dwExtra;

LPBITMAPINFO lpbi = ImgGetInfo ( hImage ) ;

rect.top = rect.left = 0 ;

rect.bottom = lpbi->bmiHeader.biHeight - 1;

rect.right = lpbi->bmiHeader.biWidth - 1;

dwExtra = (10 << 16) | 5;

ImgDrawImageFX( hImage, hDC, &rect, NULL, IMFX_MOSAIC, 0, dwExtra, NULL, 0, 0, hPal);