L_PaintDCOverlayCallback

#include "l_bitmap.h"

L_LTDIS_API L_INT L_PaintDCOverlayCallback(pCallbackData, pBitmap, nIndex, pSrc, pClipSrc, pDst, pClipDst, uROP3);

pPAINTCALLBACKDATA pCallbackData;

/* pointer to the callback data structure */

pBITMAPHANDLE pBitmap;

/* pointer to the main bitmap handle containing the overlay */

L_INT nIndex;

/* the index of the overlay bitmap used for painting */

L_RECT * pSrc;

/* the source rectangle (in pBitmap coordinates, not in overlay coordinates!) */

L_RECT * pClipSrc;

/* the source clipping rectangle (in pBitmap coordinates, not in overlay coordinates!) */

L_RECT * pDst;

/* the destination rectangle (in pBitmap coordinates, not in overlay coordinates) */

L_RECT * pClipDst;

/* the destination clipping rectangle (in pBitmap coordinates, not in overlay coordinates) */

L_UINT32 uROP3;

/* windows ROP code for display */

Paints the overlay at the specified index using custom callbacks. Use this function to paint overlays that are not automatically painted.

Parameter

Description

pCallbackData

Pointer to a structure containing the device context (DC) and the paint callbacks. The mapping mode of the device context must be MM_TEXT.

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.

pBitmap

Pointer to the bitmap handle referencing the main bitmap.

nIndex

The index of the overlay used for painting. The overlay should have a bitmap. If the overlay is embedded into a bitmap bitplane, make sure you create an overlay bitmap prior to calling this function. This index is zero-based.

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 main bitmap. You can pass NULL to use the default, which matches the main bitmap.

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 main bitmap. You can pass NULL to use the default, which matches the main bitmap.

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.

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.

uFlags

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.

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.

Returns

SUCCESS

The function was successful.

< 1

An error occurred. Refer to Return Codes.

Comments

The HDC you are painting to should stored in the PAINTCALLBACKDATA structure. Please refer to its documentation for details on which GDI functions you can override.

This function will paint an overlay bitmap. For more information on the paint rectangles, see L_PaintDC. L_PaintDC will paint all the overlays that have OVERLAY_AUTOPAINT set in the uFlags member of the OVERLAYATTRIBUTES structure. The overlays are painted in ascending index order: overlay 0 is painted first, then overlay 1, etc.

Use this function to manually paint an overlay. For example, to change the order in which the overlays are painted, clear the OVERLAY_AUTOPAINT flag from the uFlags member of the overlay's OVERLAYATTRIBUTES structure and call L_PaintDCOverlayCallback directly.

To temporarily make an overlay top-most, call L_PaintDCOverlayCallback after L_PaintDC. To permanently make an overlay top-most, change its index and give it the highest defined index.

The overlay bitmap's 1 pixels are painted with the color set in the crColor member of the OVERLAYATTRIBUTES structure. The overlay bitmap's 0 pixels are considered transparent.

For more information on the overlay attributes, including the OVERLAY_AUTOPAINT flag and crColor, refer to OVERLAYATTRIBUTES.

Required DLLs and Libraries

LTDIS

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

Windows 2000 / XP/Vista.

See Also

Functions:

L_PaintDC, L_PaintDCCallback, L_SetOverlayAttributes, L_UpdateBitmapOverlayBits, L_SetOverlayBitmap, L_BricksTextureBitmap, L_CanvasBitmap, L_DisplaceMapBitmap, L_FragmentBitmap, L_VignetteBitmap

Structures:

PAINTCALLBACKDATA, OVERLAYATTRIBUTES

Topics:

Raster Image Functions: Displaying Images

 

Raster Image Functions: Combining Images

 

Overlay Overview

 

Raster Image Functions: Using Custom Paint

 

Paint Using Custom Callbacks

Example

This example assumes pBitmap contains overlays. It will make it look as if overlay 0 is topmost The example also assumes hDC and pDest have been initialized elsewhere. 

L_INT PaintDCCallbackOverlayExample(HDC hDC, pBITMAPHANDLE pBitmap, LPRECT pDest)
{
   L_INT nRet;
   PAINTCALLBACKDATA PaintCallbackData;

   /* Initialize the paint callback data structure */
   memset(&PaintCallbackData, 0, sizeof(PaintCallbackData));
   PaintCallbackData.uStructSize = sizeof(PAINTCALLBACKDATA);
   PaintCallbackData.pDisplay = hDC;

   /* set the paint callbacks for the GDI functions you are overriding here

        PaintCallbackData.pIsCompatibleDC = MyIsCompatibleDC;
        PaintCallbackData.pStretchDIBits = MyStretchDIBits;
        etc
   */

   nRet = L_PaintDCCallback(&PaintCallbackData, pBitmap, NULL, NULL, pDest, NULL, SRCCOPY); 
   if(nRet != SUCCESS)
      return nRet;
   nRet = L_PaintDCOverlayCallback(&PaintCallbackData, pBitmap, 0, NULL, NULL, pDest, NULL, SRCCOPY); 
   if(nRet != SUCCESS)
      return nRet;
   /* Now overlay 0 is topmost (it covers all the other overlays) */
   return SUCCESS;
}