LBitmap::GrayScaleToMultitone

#include "ltwrappr.h"

virtual L_INT LBitmap::GrayScaleToMultitone (uToneType, uDistType, pColor, pGradient, uFlags)

L_UINT uToneType;

/* number of colors to add */

L_UINT uDistType;

/* type of color shade distribution */

LPCOLORREF pColor;

/* array of RGB colors that will be mixed with the bitmaps palette */

LPRGBQUAD * pGradient;

/* pointer to array of palette entries that hold the user-defined color shades */

L_UINT uFlags;

/* flag that indicates whether colors will be mixed or replaced */

Converts a grayscale bitmap into a colored one by mixing or replacing the original values of the pixels with one or more new colors.

Parameter

Description

uToneType

Flag that indicates the number of colors to add to the grayscale bitmap. Possible values are:

 

Value

Meaning

 

DT_MONOTONE

[0x0000] Add one color.

 

DT_DUOTONE

[0x0001] Add two colors.

 

DT_TRITONE

[0x0002] Add three colors.

 

DT_QUADTONE

[0x0003] Add four colors.

uDistType

Flag that indicates the source of the colors to be added to the bitmap. Possible values are:

 

Value

Meaning

 

DT_LINEAR

[0] Use the linear gradient from dark to light, generated by the toolkit. If this flag is set, LEADTOOLS will ignore the pGradient parameter and update the pColor parameter with an array of colors generated by the toolkit.

 

DT_USERDEFINE

[1] Use the user-defined gradient in the pGradient parameter.

pColor

Pointer to an array of RGB colors, that will be added to the grayscale bitmap. This parameter is ignored when the uDistType parameter is set to DT_USERDEFINE. If the toolkit is generating the gradient colors, the user sets the desired base color(s) in this parameter when LBitmap::GrayScaleToMultitone is called. The number of entries in the array depends on the value of uToneType: 1 for DT_MONOTONE, 2 for DT_DUOTONE, 3 for DT_TRITONE, 4 for DT_QUADTONE. When the toolkit generates the array of gradient colors, this parameter will be updated with that array.

pGradient

Pointer to a user-defined array of palette entries that will hold the set of color shade gradients. This parameter is used when the uDistType parameter is set to DT_USERDEFINE.

 

The number of entries in this array should be 256 entries for each TONE.

uFlags

Flag used to determine whether the new colors replace the old colors, or whether the new colors will be mixed with the old colors. Possible values are:

 

Value

Meaning

 

DT_MIX

[0x0000] Mix the old colors with the new ones

 

DT_REPLACE

[0x0001] Replace the old colors with the new ones

Returns

SUCCESS

The function was successful.

< 1

An error occurred. Refer to Return Codes.

Comments

This function was designed for use with grayscale bitmaps. If the bitmap being used is not grayscale, this function only affects those pixels or areas of the bitmap where Red=Green=Blue.

Monotone conversion is possible by setting uFlags to DT_REPLACE, which clears the palette.

This function gives you the option of having the toolkit generate the array of colors to use or creating the array of colors to use yourself.

To have the toolkit generate the array of colors:

(a)

If the bitmap is binary, call LBitmap::GrayScaleToMultitone with uToneType set to DT_MONOTONE, uDistType set to DT_LINEAR and the color you wish to use set in pColor. The LBitmapBase::IsGrayScale function will be called by LBitmap::GrayScaleToDuotone to determine the kind of grayscale palette being used. If LBitmapBase::IsGrayScale returns GRAY_ORDEREDINVERSE or GRAY_NOTORDERED, then the color passed in the pColor parameter to LBitmap::GrayScaleToMultitone will become the first color in the array generated by the toolkit, and the toolkit will create the second color in the array. The pColor array will be updated with these two colors.

 

If LBitmapBase::IsGrayScale returns a value other than GRAY_ORDEREDINVERSE or GRAY_NOTORDERED, then the color passed in the pColor parameter to LBitmap::GrayScaleToMultitone will become the second color in the array generated by the toolkit, and the toolkit will create the first color in the array. The pColor parameter will be updated with these two colors.

(b)

If the bitmap is grayscale (not binary) call LBitmap::GrayScaleToMultitone with uDistType set to DT_LINEAR. The LBitmap::GrayScaleToMultitone function will take the color(s) passed to it in the pColor parameter and generate a 256 color gradient for each color.

 

If the uToneType is set to DT_DUOTONE, set two colors in the pColor parameter. The toolkit will create a 256 color array for each color. The pColor array will be updated with all 512 colors.

 

If the uToneType is set to DT_TRITONE, set three colors in the pColor parameter. The toolkit will create a 256 color array for each color. The pColor array will be updated with all 768 colors.

 

If the uToneType is set to DT_QUADTONE, set four colors in the pColor parameter. The toolkit will create a 256 color array for each color. The pColor array will be updated with all 1024 colors.

(c)

If the bitmap is not grayscale (it is color) call LBitmap::GrayScaleToMultitone with uDistType set to DT_LINEAR. The LBitmap::GrayScaleToMultitone function will take the color(s) passed to it in the pColor parameter and generate a 256 color gradient for each color. (See the expanded explanation in i, ii and iii of (b) above.) These colors will be used to change only those pixels in the color image for which Red = Green = Blue.

To use a user-defined array of colors:

(a)

If the bitmap is binary, call LBitmap::GrayScaleToMultitone with uToneType set to DT_MONOTONE, uDistType set to DT_USERDEFINE and the two colors you wish to use in the pGradient parameter.

(b)

If the bitmap is grayscale (not binary) call LBitmap::GrayScaleToMultitone with uDistType set to DT_USERDEFINE.

 

If the uToneType is set to DT_DUOTONE, set 512 colors (256 for each basic color) in the pGradient parameter.

 

If the uToneType is set to DT_TRITONE, set 768 colors (256 for each basic color) in the pGradient parameter.

 

If the uToneType is set to DT_QUADTONE, set 1024 colors (256 for each basic color) in the pGradient parameter.

(c)

If the bitmap is not grayscale (it is color) call LBitmap::GrayScaleToMultitone with uDistType set to DT_USERDEFINE. (See the expanded explanation in i, ii and iii of (b) above.) These colors will be used to change only those pixels in the color image for which Red = Green = Blue.

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 only in the Document/Medical toolkits.

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.

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

LTIMGCLR

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.

See Also

Functions:

LBitmapBase::GrayScale, LBitmapBase::IsGrayScale, LBitmap::GrayScaleToDuotone

Topics:

Raster Image Functions: Doing Color Expansion or Reduction

 

Grayscale Images

 

Using Color Values in LEADTOOLS

 

Color Halftones and Halftone Images

 

Raster Image Functions: Working with Color Halftones, Halftones, and Grayscale Images

Example

This example applies Duotone conversion to it. 

L_INT LBitmap__GrayScaleToMultitoneExample(LAnimationWindow *BitmapWindow) 
{
   L_INT nRet;
   COLORREF     crColor[2];        /* New Color */
   /* Change the bitmap to grayscale bitmap*/
   nRet =BitmapWindow->GrayScale (8);
   if(nRet !=SUCCESS)
      return nRet;
   /* The new colors */
   crColor[0] = RGB(255, 255, 0); 
   crColor[1] = RGB(255, 0, 0); 
   /* Apply Multitone conversion */
   nRet =BitmapWindow->GrayScaleToMultitone(DT_DUOTONE,DT_LINEAR, crColor, NULL, DT_REPLACE);
   if(nRet !=SUCCESS)
      return nRet;
   return SUCCESS;
}