Sets the overlay bitmap for a certain index.


#include "l_bitmap.h"

L_LTKRN_API L_INT L_SetOverlayBitmap(pBitmap, nIndex, pOverlayBitmap, uFlags)



Pointer to the bitmap handle referencing the main bitmap.

L_INT nIndex

The index of the overlay for which to set the bitmap This index is zero-based.

pBITMAPHANDLE pOverlayBitmap

Pointer to the overlay bitmap handle which contains the new overlay bitmap. This can be NULL, in which case the corresponding overlay bitmap will be freed.

L_UINT uFlags

Flags that determine how to set the bitmap for the overlay. You cannot combine these flags. Possible values are:

Value Meaning
OVERLAY_COPY [0x0000] A copy of the overlay bitmap is inserted in the overlay list. pOverlayBitmap will not be affected.
OVERLAY_NOCOPY [0x0001] pOverlayBitmap is set into the overlay list without making a copy. You should be careful when modifying the overlay bitmap because you can modify/invalidate the entry in the overlay bitmap list.
OVERLAY_MOVE [0x0003] pOverlayBitmap is moved into the overlay list. It will also be reset, so you cannot make changes to it. This is recommended over OVERLAY_NOCOPY.


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


Calling this function with a valid bitmap handle set in pOverlayBitmap frees the old overlay bitmap at the specified index and sets the overlay bitmap at the index to the new bitmap referenced by pOverlayBitmap. If pOverlayBitmap is NULL, the old overlay bitmap is freed and the size is reset to:

OverlayWidth = BITMAPWIDTH(pBitmap) - pOverlayBitmap.ptOrigin.x

OverlayHeight = BITMAPHEIGHT(pBitmap) - pOverlayBitmap.ptOrigin.y


If uFlags is OVERLAY_NOCOPY and the overlay bitmap is allocated, all the members from the pOverlayBitmap structure are copied into the overlay array. This means whenever you update the data from pOverlayBitmap, the overlay bitmap is changed too. Great care should be taken when using this flag because you can invalidate the overlay bitmap handle stored in the array. For example, if you free the overlay bitmap, the data pointed to by the overlay bitmap from the internal array is also freed, but the array does not know that this has happened and thinks the data pointer is still valid. If the overlay bitmap is accessed in some way, a crash will occur. A safer way of quickly setting the data is to use OVERLAY_MOVE.

If uFlags is OVERLAY_MOVE, the data from the pOverlayBitmap is copied into the overlay array and then the pOverlayBitmap structure is erased. This means that you can do anything with the pOverlayBitmap structure and the overlay bitmap stored in the array will be unaffected. This is the most efficient way of setting the overlay bitmap, because no copy will take place.

You can change the size of the overlay bitmap by calling L_SetOverlayBitmap. Note that you can call L_SetOverlayBitmap with an unallocated bitmap. In that case, only the width and height are used from the overlay bitmap. If an overlay bitmap already exists, it will be freed and the new width/height will be set. After doing this, you must call L_SetOverlayAttributes to allocate the overlay bitmap and populate it with image data from the main bitmap.

If pOverlayBitmap references a bitmap that is not 1-bit, this function will return an error indicating that the bitmap has the wrong bits per pixel.

Required DLLs and Libraries


Win32, x64, Linux.

See Also




This example will load an overlay bitmap and sets its color and a few attributes.

L_INT SetOverlayBitmapExample(pBITMAPHANDLE  pBitmap, 
                                              LPTSTR         pszName, 
                                              L_INT          nIndex, 
                                              COLORREF       crColor) 
   L_INT             nRet; 
   BITMAPHANDLE      OverlayBitmap; 
   OVERLAYATTRIBUTES OverlayAttributes; 
   // load and then set the overlay bitmap 
   nRet = L_LoadBitmap( pszName, &OverlayBitmap,sizeof(BITMAPHANDLE),1,ORDER_RGB,NULL,NULL); 
   if(nRet == SUCCESS) 
      nRet = L_SetOverlayBitmap( pBitmap, nIndex, &OverlayBitmap,OVERLAY_MOVE); 
   if(nRet == SUCCESS) 
      OverlayAttributes.uStructSize = sizeof(OVERLAYATTRIBUTES); 
      OverlayAttributes.crColor = crColor; 
      OverlayAttributes.uFlags = OVERLAY_AUTOPAINT; 
      if(nIndex != 3)   // auto-process all overlays except index 3 
         OverlayAttributes.uFlags |= OVERLAY_AUTOPROCESS; 
      OverlayAttributes.ptOrigin.x = nIndex * 30; 
      OverlayAttributes.ptOrigin.y = nIndex * 10; 
      OverlayAttributes.uBitPosition = (L_UINT16) (pBitmap->BitsPerPixel - nIndex - 1); 
      nRet = L_SetOverlayAttributes(pBitmap,  
                                    OVERLAYATTRIBUTES_COLOR    | 
                                    OVERLAYATTRIBUTES_FLAGS    |  
                                    OVERLAYATTRIBUTES_ORIGIN   |  
   return nRet; 

Help Version 23.0.2024.2.29
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2024 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS Raster Imaging C API Help

Products | Support | Contact Us | Intellectual Property Notices
© 1991-2023 LEAD Technologies, Inc. All Rights Reserved.