Performs a bit-block transfer of the color data corresponding to a rectangle of pixels from the specified source device context into a destination device context, while applying a special effect.
#include "l_bitmap.h"
L_LTEFX_API L_INT L_EfxEffectBlt(hdcDest, nXDest, nYDest, nWidth, nHeight, hdcSrc, nXSrc, nYSrc, uEffect, uGrain, uDelay, nSpeed, nCycles, uPass, uMaxPass, fTransparency, crTransparency, uWandWidth, crWand, uROP)
Handle to the target device context.
X coordinate of the origin of the destination rectangle.
Y coordinate of the origin of the destination rectangle.
Width of the destination rectangle.
Height of the destination rectangle.
Handle to the source device context.
X coordinate of the origin of the source rectangle.
Y coordinate of the origin of the source rectangle.
Effect to apply when painting. For valid values, refer to Effect Types.
Graining size. This is the smallest size (pixel width or height) to be updated when painting an effect. Using a small grain makes the painting smoother, but takes longer to paint. Using a large grain makes the painting more coarse, but paints faster. If the uEffect
parameter is from the Wave class this represents the duration or height of the wave. Valid values are 1 to 256.
Delay between graining steps, in milliseconds.
Speed of the wave. Valid values are 1 to 256. This parameter is valid only if the uEffect
parameter is from the Wave class.
Number of cycles or repetitions used to draw the wave. This parameter is valid only if the uEffect
parameter is from the Wave class.
Pass number when using a pattern brush. Use 1 for painting in one pass.
Maximum passes for a pattern brush. Use 1 for painting in one pass.
TRUE to implement transparency by not painting pixels of the color specified in the crTransparency
parameter; FALSE if transparency is not implemented.
COLORREF value that specifies the transparent color.
Wand width, in pixels.
COLORREF value that specifies the wand color.
Windows ROP code for display. This parameter takes the same codes as the Windows BitBlt function. For ordinary painting, use SRCCOPY.
Value | Meaning |
---|---|
SUCCESS | The function was successful. |
< 1 | An error occurred. Refer to Return Codes. |
Use this function as a replacement for the Windows BitBlt C API function when you want a special painting effect.
Use the uGrain
and uDelay
parameters to control the speed of the display. The uGrain parameter controls the size of the painting increment, and uDelay controls the time between increments.
The wand is a solid color bar that moves during an effect. Small grain sizes produce the best wand effects. Many of the effects listed in Effect Types can have a wand.
Use the uPass
and uMaxPass
parameters to paint the image in more than one pass. For example, if you want a 3-pass paint, use uMaxPass of 3 and paint 3 times, once with uPass = 1, once with uPass = 2, and once with uPass = 3.
Multipass painting for the EFX_EFFECT_PUSH_CLASS is disabled.
If the uEffect
parameter is from the Twirl class, White Turnover class, Turnover class, Replace class, Laser class, Fade Normal class, Fade Black and White class, Fade Color class or Wave Class, the uPass and uMaxPass parameters have no effect.
If the uEffect parameter is from the Fade Normal class, Fade Black and White class or Fade Color class, the uGrain parameter has no effect. However, if the uEffect parameter is from the Wave class, the uGrain
parameter contains the wave size.
If the uEffect parameter is from the White Turnover class, the Turnover class or the Replace class, the uWandWidth
and crWand
parameters have no effect. However, if the uEffect parameter is from the Fade Color class, the crWand parameter contains the bitmap color level.
The nSpeed
and nCycles
parameters have effect only if the uEffect parameter is from the Wave class.
For general information, refer to Implementing Special Effects.
Win32, x64.
This function shows how to use L_EfxEffectBlt to paint a bitmap to the screen using a special effect.
L_INT EfxEffectBltFirstExample(HWND hWnd)
{
L_INT nRet;
HDC hdcDest; // Device context for the current window
HDC hdcSrc; // Device context for the source image
BITMAPHANDLE Bitmap; // image that will be blt
HBITMAP hbmMem; // image that will be blt
HPALETTE hSavedPalette = NULL; // Temporary copy of the current system palette
HPALETTE hPaintPal = NULL; // The palette that we will use to paint
L_INT nBitsPerPixel;
// Get the device context
hdcDest = GetDC(hWnd);
// Check the device to see if we need a palette
nBitsPerPixel = GetDeviceCaps(hdcDest, BITSPIXEL) * GetDeviceCaps(hdcDest, PLANES);
// Load an image to BLT
// Load the image as screen bit-depth
nRet = L_LoadBitmap(MAKE_IMAGE_PATH("IMAGE1.CMP"), &Bitmap, sizeof(BITMAPHANDLE), (nBitsPerPixel <= 8) ? nBitsPerPixel : 24, ORDER_BGR, NULL, NULL);
if (nRet != SUCCESS)
return nRet;
// Create the source DC
hdcSrc = CreateCompatibleDC(hdcDest);
// Convert the image to DDB and select it into the source dc
hbmMem = L_ConvertToDDB(hdcDest, &Bitmap);
hbmMem = (HBITMAP)SelectObject(hdcSrc, hbmMem);
if (nBitsPerPixel <= 8)
{
hPaintPal = L_CreatePaintPalette(hdcDest, &Bitmap);
hSavedPalette = SelectPalette(hdcDest, hPaintPal, FALSE);
// Realize our palette
RealizePalette(hdcDest);
}
// Paint the image using nRet = L_EfxEffectBlt and 3 steps
nRet = L_EfxEffectBlt(hdcDest, // handle to target dc
0, // x-coordinate of destination rectangle's upper-left corner
0, // x-coordinate of destination rectangle's upper-left corner
Bitmap.Width, // width of destination rectangle
Bitmap.Height, // height of destination rectangle
hdcSrc, // handle to source device context
0, // x-coordinate of source rectangle's upper-left corner
0, // y-coordinate of source rectangle's upper-left corner
EFX_EFFECT_WIPE_L_TO_R, // paint effect to use
1, // graining size
1, // delay between graining steps
0, // speed of the wave
0, // number of cycles or repetitions
1, // step number for the pattern brush
3, // maximum steps for the pattern brush
FALSE, // do not use transparency
0, // transparent color, black
3, // wand width
RGB(255, 0, 0), // wand color, red
SRCCOPY); // Windows raster operation code
if (nRet != SUCCESS)
return nRet;
nRet = L_EfxEffectBlt(hdcDest, // handle to target DC
0, // x-coordinate of destination rectangle's upper-left corner
0, // x-coordinate of destination rectangle's upper-left corner
Bitmap.Width, // width of destination rectangle
Bitmap.Height, // height of destination rectangle
hdcSrc, // handle to source device context
0, // x-coordinate of source rectangle's upper-left corner
0, // y-coordinate of source rectangle's upper-left corner
EFX_EFFECT_WIPE_R_TO_L, // paint effect to use
1, // graining size
1, // delay between graining steps
0, // speed of the wave
0, // number of cycles or repetitions
2, // step number for the pattern brush
3, // maximum steps for the pattern brush
FALSE, // do not use transparency
0, // transparent color, black
3, // wand width
RGB(255, 0, 0), // wand color, red
SRCCOPY); // Windows raster operation code
if (nRet != SUCCESS)
return nRet;
nRet = L_EfxEffectBlt(hdcDest, // handle to target dc
0, // x-coordinate of destination rectangle's upper-left corner
0, // x-coordinate of destination rectangle's upper-left corner
Bitmap.Width, // width of destination rectangle
Bitmap.Height, // height of destination rectangle
hdcSrc, // handle to source device context
0, // x-coordinate of source rectangle's upper-left corner
0, // y-coordinate of source rectangle's upper-left corner
EFX_EFFECT_WIPE_L_TO_R, // paint effect to use
1, // graining size
1, // delay between graining steps
0, // speed of the wave
0, // number of cycles or repetitions
3, // step number for the pattern brush
3, // maximum steps for the pattern brush
FALSE, // do not use transparency
0, // transparent color, black
3, // wand width
RGB(255, 0, 0), // wand color, red
SRCCOPY); // Windows raster operation code
if (nRet != SUCCESS)
return nRet;
// Restore the old palette
if (hPaintPal)
{
SelectPalette(hdcDest, hSavedPalette, FALSE);
DeleteObject(hPaintPal);
}
// Release the device context
ReleaseDC(hWnd, hdcDest);
DeleteDC(hdcSrc);
DeleteObject(hbmMem);
L_FreeBitmap(&Bitmap);
return SUCCESS;
}
// This function shows how to use L_EfxEffectBlt with wave effect
L_INT EfxEffectBltSecondExample(HWND hWnd)
{
L_INT nRet;
HDC hdcDest; // Device context for the current window
HDC hdcSrc; // Device context for the source image
BITMAPHANDLE Bitmap; // image that will be blt
HBITMAP hbmMem; // image that will be blt
HPALETTE hSavedPalette = NULL; // Temporary copy of the current system palette
HPALETTE hPaintPal = NULL; // The palette that we will use to paint
L_INT nBitsPerPixel;
// Get the device context
hdcDest = GetDC(hWnd);
// Check the device to see if we need a palette
nBitsPerPixel = GetDeviceCaps(hdcDest, BITSPIXEL) * GetDeviceCaps(hdcDest, PLANES);
// Load an image to BLT
// Load the image as screen bit-depth
nRet = L_LoadBitmap(MAKE_IMAGE_PATH("IMAGE1.CMP"), &Bitmap, sizeof(BITMAPHANDLE), (nBitsPerPixel <= 8) ? nBitsPerPixel : 24, ORDER_BGR, NULL, NULL);
if (nRet != SUCCESS)
return nRet;
// Create the source DC
hdcSrc = CreateCompatibleDC(hdcDest);
// Convert the image to DDB and select it into the source dc
hbmMem = L_ConvertToDDB(hdcDest, &Bitmap);
hbmMem = (HBITMAP)SelectObject(hdcSrc, hbmMem);
if (nBitsPerPixel <= 8)
{
hPaintPal = L_CreatePaintPalette(hdcDest, &Bitmap);
hSavedPalette = SelectPalette(hdcDest, hPaintPal, FALSE);
// Realize our palette
RealizePalette(hdcDest);
}
nRet = L_EfxEffectBlt(hdcDest, // handle to target dc
0, // x-coordinate of destination rectangle's upper-left corner
0, // x-coordinate of destination rectangle's upper-left corner
Bitmap.Width, // width of destination rectangle
Bitmap.Height, // height of destination rectangle
hdcSrc, // handle to source device context
0, // x-coordinate of source rectangle's upper-left corner
0, // y-coordinate of source rectangle's upper-left corner
EFX_EFFECT_WAVE_TB, // paint effect to use
1, // graining size
1, // delay between graining steps
20, // speed of the wave
1, // number of cycles or repetitions
1, // step number for the pattern brush
3, // maximum steps for the pattern brush
FALSE, // do not use transparency
0, // transparent color, black
3, // wand width
RGB(255, 0, 0), // wand color, red
SRCCOPY); // Windows raster operation code
if (nRet != SUCCESS)
return nRet;
// Restore the old palette
if (hPaintPal)
{
SelectPalette(hdcDest, hSavedPalette, FALSE);
DeleteObject(hPaintPal);
}
// Release the device context
ReleaseDC(hWnd, hdcDest);
DeleteDC(hdcSrc);
DeleteObject(hbmMem);
L_FreeBitmap(&Bitmap);
return SUCCESS;
}