#include "l_bitmap.h"

L_LTIMGSFX_API L_INT L_ColoredBallsBitmap(pBitmap, uNumBalls, uSize, uSizeVariation, nHighLightAng, crHighLight, crBkgColor, crShadingColor, pBallColors, uNumOfBallColors, uAvrBallClrOpacity, uBallClrOpacityVariation, uRipple, uFlags)

This function adds colored balls to the bitmap. Various parameters control the color and appearance of the balls.



Pointer to the bitmap handle referencing the bitmap to be changed.

L_UINT uNumBalls

Number of balls that will be drawn in the image.

L_UINT uSize

Average ball size, in pixels.

L_UINT uSizeVariation

Ball size variation. Valid values range from 0 to 100. Use 0 to have all balls the same size. Use 100 to have the size vary from 0 to 2 X uSize.

L_INT nHighLightAng

Light source direction of the highlight color on the ball. This value is in hundredths of degrees (+/-). A positive value will rotate the highlight color clockwise, while a negative value will rotate the highlight color counter-clockwise. Possible values range from 36000 to + 36000.

COLORREF crHighLight

Highlight color.


Background color.

COLORREF crShadingColor

Shade (or gradient) color.

COLORREF *pBallColors

Pointer to an array of ball colors.

L_UINT uNumOfBallColors

The number of ball colors.

L_UINT uAvrBallClrOpacity

Average ball color opacity. Valid values range from 0 to 255 for 8-bit , 0 to 4095 for 12-bit and 0 to 65535 for 16-bit.

L_UINT uBallClrOpacityVariation

Ball color opacity variation. Valid values range from 0 to 100. Use 0 to have all pixels assigned the same opacity. Use 100 to have the opacity vary from 0 to 2 X uAvrBallClrOpacity.

L_UINT uRipple

The number of shades that are used to produce the background. This value is divided internally by 100. For example, if uRipple = 200 the actual frequency is 2. This value is ignored if the CLRBALLS_SHADING_SINGLE flag is set.

L_UINT uFlags

Flags that indicate which background color, shade (or gradient) type, ball type and ball color type to use. You can use a bit wise OR (|) to specify one flag from each group. Possible values are:

Value Meaning
How to draw the shading:
CLRBALLS_SHADING_SINGLE [0x0001] Use only the background color (i.e. no shading).
CLRBALLS_SHADING_LEFTRIGHT [0x0002] Draw shading as vertical lines that move from left to right.
CLRBALLS_SHADING_TOPBOTTOM [0x0003] Draw shading as horizontal lines that move from top to bottom.
CLRBALLS_SHADING_CIRCULAR [0x0004] Draw shading as concentric circles.
CLRBALLS_SHADING_ELLIPTICAL [0x0005] Draw shading as concentric ellipses.
Type of ball to use:
CLRBALLS_STICKER [0x0010] Use Balls that will overlap like stickers.
CLRBALLS_BALL [0x0020] Use Balls that will adjust like bubbles.
How to treat the background:
CLRBALLS_IMAGE [0x0100] Make the background the same as the image.
CLRBALLS_COLOR [0x0200] Make the background using crBkgColor and crShadingColor with the specified shade type.
Type of ball coloring to use:
CLRBALLS_BALLCLR_MASK [0x1000] Have the Ball color block image colors.
CLRBALLS_BALLCLR_OPACITY [0x2000] Use the opacity value when combining image colors with ball colors.


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.

The CLRBALLS_STICKER flag produces balls with more distinct edges than the CLRBALLS_BALL option.

For an example, click here

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

This function supports 12 and 16-bit grayscale and 48 and 64-bit color images. Support for 12 and 16-bit grayscale and 48 and 64-bit color images is available in the Document and Medical Imaging toolkits.

If the bitmap has a region, this function works only on the region. If the bitmap does not have a region, this function works on the entire bitmap.

This function does not support 32-bit grayscale images. It returns the error code ERROR_GRAY32_UNSUPPORTED if a 32-bit grayscale image is passed to this function.

Required DLLs and Libraries


Win32, x64.

See Also




The following example loads a bitmap, and applies the colored ball effect:

L_INT ColoredBallsBitmapExample(L_VOID) 
   L_INT nRet; 
   BITMAPHANDLE LeadBitmap; 
   COLORREF       pBallColors[7]; 
   pBallColors[0] = RGB(230,50,50); 
   pBallColors[1] = RGB(230,200,160); 
   pBallColors[2] = RGB(255,255,128); 
   pBallColors[3] = RGB(240,50,100); 
   pBallColors[4] = RGB(255,255,180); 
   pBallColors[5] = RGB(170,240,100); 
   pBallColors[6] = RGB(255,255,255); 
   /* Load the bitmap, keeping the bits per pixel of the file */ 
   nRet = L_LoadBitmap (MAKE_IMAGE_PATH(TEXT("cannon.jpg")), &LeadBitmap, sizeof(BITMAPHANDLE), 0, ORDER_BGR,NULL,NULL);  
   if(nRet !=SUCCESS) 
      return nRet; 
   /*Apply the effect*/ 
   nRet = L_ColoredBallsBitmap(&LeadBitmap, 1000, 25, 15, 31500, RGB(255,255,255), 
                               RGB(255,0,0), RGB(255,255,0), pBallColors, 7, 64, 10, 100,  
      if(nRet !=SUCCESS) 
         return nRet; 
   nRet = L_SaveBitmap(MAKE_IMAGE_PATH(TEXT("Result.BMP")), &LeadBitmap, FILE_BMP, 24, 0, NULL); 
   if(nRet !=SUCCESS) 
      return nRet; 
   //free bitmap  
   return SUCCESS; 

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

LEADTOOLS Raster Imaging C API Help