L_GrayScaleToMultitone

#include "l_bitmap.h"

L_INT EXT_FUNCTION L_GrayScaleToMultitone(pBitmap, uToneType, uDistType, pColor, pGradient, uFlags)

pBITMAPHANDLE pBitmap;	/* pointer to the bitmap handle */
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 bitmap’s palette */
LPRGBQUAD L_FAR * 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. This function is available in the Raster Pro and above toolkits.

Parameter	Description
pBitmap	Pointer to the bitmap handle referencing the bitmap.
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_USER. If the toolkit is generating the gradient colors, the user sets the desired base color(s) in this parameter when L_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_USER.
	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 L_GrayScaleToMultitone with uToneType set to DT_MONOTONE, uDistType set to DT_LINEAR and the color you wish to use set in pColor. The L_IsGrayScaleBitmap function will be called by L_GrayScaleToDuotone to determine the kind of grayscale palette being used. If L_IsGrayScaleBitmap returns GRAY_ORDEREDINVERSE or GRAY_NOTORDERED, then the color passed in the pColor parameter to L_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 L_IsGrayScaleBitmap returns a value other than GRAY_ORDEREDINVERSE or GRAY_NOTORDERED, then the color passed in the pColor parameter to L_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 L_GrayScaleToMultitone with uDistType set to DT_LINEAR. The L_GrayScaleToMultitone function will take the color(s) passed to it in the pColor parameter and generate a 256 color gradient for each color.
	(i)	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.
	(ii)	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.
	(iii)	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 L_GrayScaleToMultitone with uDistType set to DT_LINEAR. The L_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 L_GrayScaleToMultitone with uToneType set to DT_MONOTONE, uDistType set to DT_USER and the two colors you wish to use in the pGradient parameter.
(b)	If the bitmap is grayscale (not binary) call L_GrayScaleToMultitone with uDistType set to DT_USER.
	(i)	If the uToneType is set to DT_DUOTONE, set 512 colors (256 for each basic color) in the pGradient parameter.
	(ii)	If the uToneType is set to DT_TRITONE, set 768 colors (256 for each basic color) in the pGradient parameter.
	(iii)	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 L_GrayScaleToMultitone with uDistType set to DT_USER. (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.

Required DLLs and Libraries

LTIMG

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 95 / 98 / Me, Windows 2000 / XP.

Functions:	L_GrayScaleBitmap, L_IsGrayScaleBitmap, L_GrayScaleToDuotone
Topics:	Raster Image Functions: Doing Color Expansion or Reduction
	Grayscale Images
	Using Color Values in LEADTOOLS
	Color Halftone and Halftone Images