Creates or updates the bitmap region by adding a region that consists of all the pixels of a specified color.


#include "l_bitmap.h"

L_LTDIS_API L_INT L_SetBitmapRgnColor(pBitmap, crColor, uCombineMode)



Pointer to the bitmap handle referencing the bitmap where the region is to be created or updated.


The COLORREF value that specifies the color to use for the region. You can specify a COLORREF value, such as the return value of the Windows RGB macro, or you can use the PALETTEINDEX macro to specify a palette color.

L_UINT uCombineMode

The action to take regarding the existing bitmap region, if one is defined. For descriptions of the possible values, refer to Creating a Bitmap Region.


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


This function does not support signed data images. It returns the error code ERROR_SIGNED_DATA_NOT_SUPPORTED if a signed data image is passed to this function.

You specify the color using a COLORREF value, which is a Windows-defined data type. You can assign the value using the Windows RGB macro.

To update an existing region, you specify how the new region is to be combined with the existing one. For descriptions of the possibilities, refer to Creating a Bitmap Region.

You can use this function to simulate the use of a transparent color as follows:

  1. Call the L_SetBitmapRgnColor function, with the transparent color in the crColor parameter and L_RGN_SETNOT in the uCombineMode parameter.

  2. Call the L_PaintRgnDC function to paint the resulting region, which includes everything in the bitmap, except the transparent color.

In the Document and Medical Imaging toolkits, the COLORREF value may represent a 16 bit grayscale value if pBitmap is a 12 or 16-bit grayscale bitmap, or a 32-bit grayscale value if pBitmap is a 32-bit grayscale bitmap. So that the value is not confused with an RGB value, the COLORREF_GRAY16 mask (0x04000000) is set. In this case (0x0400YYYY), the lower 16 bits (0xYYYY) of the COLORREF value represent the 16-bit grayscale value. (0x0400FFFF is 16-bit white and 0x04000000is 16-bit black.) This is not a standard Windows value. Therefore, LEADTOOLS functions will recognize a COLORREF having this format, but Windows functions will not. For information on how to use a 16-bit grayscale COLORREF in a non-LEADTOOLS function, refer to L_GetPixelColor.

If working with 12 and 16-bit grayscale, and (crLower and crUpper) values represent the 16-bit grayscale values, then the function will work on the data. For example, to select the rage between 100 and 130:

nValue = 100;
rgbLo = nValue | COLORREF_GRAY16;
nValue = 130;
rgbHi = nValue | COLORREF_GRAY16;

Required DLLs and Libraries


Win32, x64, Linux.

See Also




For a complete sample code, refer to the FEATURE3 example.
This example creates a region that includes all pixels of a specified color.
It then fills the region with blue.

L_INT SetBitmapRgnColorExample(pBITMAPHANDLE pBitmap) 
   L_INT       nRet; 
   L_COLORREF  RgnColor;         /* Color to use when defining the region */ 
   L_INT       XOffset, YOffset; /* Pixel coordinates for getting a color from the bitmap */ 
   /* Load the bitmap, at its own bits per pixel */ 
   if (pBitmap->Flags.Allocated) 
   nRet = L_LoadBitmap((L_TCHAR*)MAKE_IMAGE_PATH("Image1.cmp"), pBitmap, sizeof(BITMAPHANDLE), 0, ORDER_BGR, NULL, NULL); 
   if (nRet != SUCCESS) 
      return nRet; 
   /* Posterize the bitmap to decrease the number of colors */ 
   nRet = L_PosterizeBitmap(pBitmap, 16, 0); 
   if (nRet != SUCCESS) 
      return nRet; 
   /* Specify a pixel in the upper left of the displayed image */ 
   XOffset = BITMAPWIDTH(pBitmap) / 8; 
   YOffset = BITMAPHEIGHT(pBitmap) / 8; 
   /* Adjust the YOffset in case the view perspective is not TOP_LEFT */ 
   nRet = L_PointToBitmap(pBitmap, TOP_LEFT, &XOffset, &YOffset); 
   if (nRet != SUCCESS) 
      return nRet; 
   /* Get the color of the specified pixel */ 
   RgnColor = L_GetPixelColor(pBitmap, YOffset, XOffset); 
   /* Create a region that includes all pixels of that color */ 
   nRet = L_SetBitmapRgnColor(pBitmap, RgnColor, L_RGN_SET); 
   if (nRet != SUCCESS) 
      return nRet; 
   /* Fill the region with blue */ 
   nRet = L_FillBitmap(pBitmap, RGB(0, 0, 255)); 
   if (nRet != SUCCESS) 
      return nRet; 
   /* Free the region */ 
   nRet = L_FreeBitmapRgn(pBitmap); 
   if (nRet != SUCCESS) 
      return nRet; 
   return SUCCESS; 

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.