In This Topic ▼

L_PaintDCEffect

Summary

Applies an effect when painting a bitmap to a screen. The effect, commonly used for slide show transitions, specifies how the image is painted, not how it looks when painting is finished.

Syntax

#include "l_bitmap.h"

L_LTEFX_API L_INT L_PaintDCEffect(hDC, pBitmap, pSrc, pClipSrc, pDst, pClipDst, uROP3, uEffect)

Parameters

HDC hDC

Handle to a device context, such as a screen, to use as the display surface. The mapping mode of the device context must be MM_TEXT.

pBITMAPHANDLE pBitmap

Pointer to the bitmap handle referencing the bitmap to paint.

LPRECT pSrc

Pointer to the Windows RECT structure that specifies the part of the bitmap to use as the display source.

The coordinates in the RECT structure are relative to the bitmap. You can pass NULL to use the default, which matches the bitmap.

LPRECT pClipSrc

Pointer to the Windows RECT structure that specifies the portion of the display source to paint. Generally, this is used for updating the display when part of the source bitmap has changed.

The coordinates in the RECT structure are relative to the bitmap. You can pass NULL to use the default, which matches the bitmap.

LPRECT pDst

Pointer to the Windows RECT structure that determines how the source rectangle is scaled and how the image is positioned in the device context.

The coordinates in the RECT structure are relative to the device context. There is no default for this parameter. You must specify the RECT structure.

LPRECT pClipDst

Pointer to the Windows RECT structure that specifies the portion of the display rectangle to paint. Generally, this is used for updating changes in the display surface, such as when a user moves another window, uncovering a part of the image that had been covered up.

The coordinates in the RECT structure are relative to the device context. You can pass NULL to use the default, which matches the device context. In most cases, however, you should use the rectangle returned by the Windows WM_PAINT message.

L_UINT32 uROP3

The Windows ROP code that determines how the destination rectangle is updated. This parameter takes the same codes as the Windows BitBlt function. For ordinary painting, use SRCCOPY.

L_UINT uEffect

The effect to apply when painting. For valid values, refer to Effects.

Returns

Value	Meaning
SUCCESS	The function was successful.
< 1	An error occurred. Refer to Return Codes.

Comments

If the screen has fewer colors than the image, this function dithers the output to that display surface without affecting the actual image data.

To update a status bar or detect a user interrupt during execution of this function, refer to L_SetStatusCallback.

Otherwise, this function works the same as L_PaintDC. For a complete explanation, refer to L_PaintDC.

L_PaintDCEffect paints an image faster if its view perspective is bottom left. LEAD CMP images have a bottom-left view perspective, but some other formats have a top-left perspective. To get uniformly fast paints on all images, you can set the perspective after you load them, as shown in the following code. (You do not have to change them back before saving them in the original format, because the save functions set the orientation for the specified format.)

if (Bitmap.ViewPerspective != BOTTOM_LEFT)   
   L_ChangeBitmapViewPerspective ( NULL, &Bitmap, sizeof(BITMAPHANDLE), BOTTOM_LEFT );

Multipass painting for the EFX_EFFECT_PUSH_CLASS is disabled.

Refer to L_EfxPaintBitmap for more control over the painting process.

Required DLLs and Libraries

LTEFX
For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

Platforms

Win32, x64.

Example

For complete sample code, refer to the \Examples\SpecialEffects\C\PaintEff demo.
This example shows the minimum requirements for using the L_PaintDCEffect function to paint an image with a palette.

L_INT PaintDCEffectExample(HWND hWnd, pBITMAPHANDLE LeadBitmap /* Bitmap handle for the image */) 
{ 
   L_INT    nRet; 
   HDC      hdc;                    // Device context for the current window 
   RECT     rLeadDest;              // Destination rectangle for painting 
   HPALETTE hSavedPalette = NULL;   // Temporary copy of the current system palette 
   HPALETTE hOurPalette = NULL;     // The palette that we will use to paint 
 
   // Get the device context 
   hdc = GetDC(hWnd); 
 
   // Set the destination rectangle to be the same as the bitmap. 
   // Other painting rectangles can take defaults. 
   SetRect(&rLeadDest, 0, 0, BITMAPWIDTH(LeadBitmap), BITMAPHEIGHT(LeadBitmap)); 
 
   // Create the palette that we will use to paint 
   hOurPalette = L_CreatePaintPalette(hdc, LeadBitmap); 
 
   // Select our palette and save the old one 
   hSavedPalette = SelectPalette(hdc, hOurPalette, FALSE); 
 
   // Realize our palette 
   RealizePalette(hdc); 
 
   // Paint the image 
   nRet = L_PaintDCEffect(hdc,   // Device context 
      LeadBitmap,                // Bitmap handle 
      NULL,                      // Default source rectangle 
      NULL,                      // Default source clip area 
      &rLeadDest,                // Destination rectangle 
      NULL,                      // Default destination clipping rectangle 
      SRCCOPY,                   // ROP3 code for a Normal Paint 
      EFFECT_SPIRAL_IN);         // Spiral effect 
   if (nRet != SUCCESS) 
      return nRet; 
 
   // Restore the old palette 
   SelectPalette(hdc, hSavedPalette, FALSE); 
 
   // Release the device context 
   ReleaseDC(hWnd, hdc); 
 
   return SUCCESS; 
}