L_ColorResBitmap

#include "l_bitmap.h"

L_LTKRN_API L_INT L_ColorResBitmap(pBitmapSrc, pBitmapDst, uStructSize, nBitsPerPixel, uFlags, pPalette, hPalette, uColors, pfnCallback, pUserData)

pBITMAPHANDLE pBitmapSrc;	/* pointer to the source bitmap handle */
pBITMAPHANDLE pBitmapDst;	/* pointer to the destination bitmap handle */
L_UINT uStructSize;	/* size in bytes, of the structure pointed to by pBitmap */
L_INT nBitsPerPixel;	/* target bits per pixel */
L_UINT uFlags;	/* processing options */
L_RGBQUAD* pPalette;	/* custom palette to use */
L_HPALETTE hPalette;	/* custom palette handle to use */
L_UINT uColors;	/* number of colors in the palette */
COLORRESCALLBACK pfnCallback;	/* optional callback function */
L_VOID* pUserData;	/* pointer to more parameters for the callback */

Converts a bitmap from any bits-per-pixel to any bits-per-pixel. This function provides flexibility in specifying the output destination and in specifying the palette to use.

Parameter	Description
pBitmapSrc	Pointer to the bitmap handle referencing the source bitmap. You can convert the bitmap in place by specifying the same one as the destination.
pBitmapDst	Pointer to the bitmap handle referencing the destination bitmap. The following are valid values:
	Value	Meaning
	Same as pBitmapSrc	Convert the bitmap in place.
	New pBITMAPHANDLE	Create a new bitmap to contain the converted data. The source bitmap remains unchanged.
	NULL	Rely on the callback function to direct the output. The source bitmap remains unchanged.
uStructSize	Size in bytes, of the structure pointed to by pBitmap, for versioning. Use sizeof(BITMAPHANDLE).
nBitsPerPixel	The number of bits per pixel to increase or decrease the bitmap to. Valid values are 1, 2, 3, 4, 5, 6, 7, 8, 12, 16, 24, 32, 48 and 64.
uFlags	Processing options. Note that the palette and dithering options are useful only when the resulting bitmap requires a palette (when it is 8 bits per pixel or less). You can combine values when appropriate by using a bitwise OR ( \| ). The following are valid values:
	Value	Meaning
	CRF_FIXEDPALETTE	[0x01] Use the fixed palette.
	CRF_OPTIMIZEDPALETTE	[0x02] Create an optimized palette, or if you supply a palette in the pPalette or hPalette parameter, but not both, supply optimized colors for specified entries in the palette.
	CRF_NETSCAPEPALETTE	[0x40] Use the fixed palette that is employed by Netscape Navigator and by Microsoft Internet Explorer.
	CRF_USERPALETTE	[0x10] Use the palette specified in the pPalette parameter, without supplying optimized colors. Please note that this cannot Or-ed with CRF_USERHPALETTE.
	CRF_USERHPALETTE	[0x0100] Use the palette specified in the hPalette parameter, without supplying optimized colors. Please note that this cannot Or-ed with CRF_USERPALETTE.
	CRF_IDENTITYPALETTE	[0x08] Insert the Windows system palette.
	CRF_FASTMATCHPALETTE	[0x20] Use a predefined table to speed conversion using your own palette. Refer to L_CreateUserMatchTable.
	CRF_BYTEORDERBGR	[0x04] Use BGR color order. This flag only has meaning when going to 16 bits per pixel or higher.
	CRF_BYTEORDERRGB	[0x00] Use RGB color. This flag only has meaning when going to 16 bits per pixel or higher.
	CRF_BYTEORDERGRAY	[0x80] Grayscale.Destination bitmap should be 12, 16 or 32-bit grayscale. 12, 16 and 32-bit grayscale images are only supported in Document and Medical Imaging toolkits.
	CRF_SLOWMATCH	[0x0200] Use with the CRF_OPTIMIZEDPALETTE flag to use a slower but more accurate matching process.
	CRF_FAVORPURECOLORS	[0x0400] Give colors that occur frequently in the image palette entries of their own in the optimized palette.
	CRF_NODITHERING	[0x00000000] Use nearest color matching.
	CRF_FLOYDSTEINDITHERING	[0x00010000] Use Floyd-Steinberg dithering.
	CRF_STUCKIDITHERING	[0x00020000] Use Stucki dithering.
	CRF_BURKESDITHERING	[0x00030000] Use Burkes dithering.
	CRF_SIERRADITHERING	[0x00040000] Use Sierra dithering.
	CRF_STEVENSONARCEDITHERING	[0x00050000] Use Stevenson Arce dithering.
	CRF_JARVISDITHERING	[0x00060000] Use Jarvis dithering.
	CRF_ORDEREDDITHERING	[0x00070000] Use ordered dithering, which is faster but less accurate than other dithering methods.
	CRF_CLUSTEREDDITHERING	[0x00080000] Use clustered dithering.
	CRF_BYTEORDERROMM	[0x0800] Use ROMM color. This flag only has meaning when going to 24 or 48 bits per pixel.
	CRF_ALPHAINIT	[0x01000000] Initialize the alpha channel for (32 or 64-bit color images) to all ones (0xFF for 8-bit alpha channels and 0xFFFF for 16-bit alpha channels). Without this flag, a created alpha channel initializes to zeros.
pPalette	The custom palette to use. Specify this parameter as follows:
	If you want to use the fixed palette or a fully optimized palette, pass NULL in this parameter and in hPalette.
	If you want to supply the entire palette, specify CRF_USERPALETTE in the uFlags parameter and pass the address of your palette. Click here to see how to fill in the palette.
	If you want the function to fill part of your palette with optimized colors, specify CRF_OPTIMIZEDPALETTE in the uFlags parameter and pass the address of your palette in pPalette and NULL in hPalette. Click here to see how to fill in the palette.
hPalette	The custom palette to use. Specify this parameter as follows:
	If you want to use the fixed palette or a fully optimized palette, pass NULL in this parameter and in pPalette.
	If you want to supply the entire palette, specify CRF_USERHPALETTE in the uFlags parameter and pass the handle of your palette. Click here to see how to fill in the palette.
	If you want the function to fill part of your palette with optimized colors, specify CRF_OPTIMIZEDPALETTE in the uFlags parameter and pass NULL for pPalette and the handle of your palette in hPalette. Click here to see how to fill in the palette.
uColors	The number of colors in the palette. Pass 0 to get the default (such as 256 for 8 bits per pixel). Otherwise, do one of the following:
	If you specify a palette in the pPalette or hPalette parameter, pass the number of entries in your palette (including reserved entries).
	If you specify NULL in the pPalette and in the hPalette parameters and you specify CRF_OPTIMIZEDPALETTE in the uFlags parameter, you can use this parameter to limit the number of colors that the function maps in the optimized palette.
pfnCallback	Optional callback function for additional processing. (The bitmap is modified the same way, whether you provide a callback function or not.)
	If you do not provide a callback function, use NULL as the value of this parameter.
	If you do provide a callback function, use the function pointer as the value of this parameter.
	L_ColorResBitmap processes a few lines at a time in an internal loop. It calls this callback function in the loop. The callback function must adhere to the function syntax described in COLORRESCALLBACK Function.
pUserData	Void pointer that you can use to pass one or more additional parameters that the callback function needs.
	To use this feature, assign a value to a variable or create a structure that contains as many fields as you need. Then, in this parameter, pass the address of the variable or structure, casting it to L_VOID *. The callback function, which receives the address in its own pUserData parameter, can cast it to a pointer of the appropriate data type to access your variable or structure.
	If the additional parameters are not needed, you can pass NULL in this parameter.

Returns

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

Comments

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.

For general information about dithering, refer to Color Resolution and Dithering.

In specifying the output destination, you can convert the bitmap in place, create a new converted bitmap, or let your callback function handle the output.

In specifying a palette, you can use simple palette options, or you can specify a palette that is tailored to your needs. The tailored palette can be any size that you specify. It can include specific colors, reserved blank entries, and open entries that this function fills with optimized colors.

If you use the same tailored palette more than once, you can improve performance by creating a table, as explained in L_CreateUserMatchTable.

NOTE: Using this function to change the color order of a 24-bit or 32-bit image (i.e. RGB to BGR) will have no effect on the image when painting or saving (to a file). If you want to change the visual appearance, you can simply swap the Order member of the BITMAPHANDLE.

Required DLLs and Libraries

LTKRN

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 2000 / XP/Vista, Windows CE.

See Also

Functions:	L_ColorResBitmapList, L_DefaultDithering,
	L_CreateUserMatchTable, L_SetUserMatchTable,
	L_FreeUserMatchTable, L_DlgColorRes , L_AutoBinarizeBitmap, L_DynamicBinaryBitmap, L_AutoBinaryBitmap
Topics:	Raster Image Functions: Doing Color Expansion or Reduction
	Raster Image Functions: Doing Color Space Conversions
	Raster Image Functions: Palettes
	Color Resolution and Dithering

Example

For complete sample code, refer to the COLOR example. This example uses L_ColorResBitmap with a callback function to paint the changed image as it is processed. Refer to the COLORRESCALLBACK function to see how the callback function paints the image data.

/* Structure used for the callback function's user data */
typedef struct tagIMAGECBPARM
{
   HWND  hwnd;     /* Current window */
   HDC   hdc;       /* Device context for the current window */
   L_INT nRow;    /* First row in the input buffer */
   HPALETTE hpalPaint; /* Paint palette handle */
   RECT rLeadDest; /* Destination rectangle for painting */ 
   RECT rLeadSource; /* Source rectangle for painting */
} IMAGECBPARM, * LPIMAGECBPARM;

/* Prototype for the COLORRESCALLBACK function */
L_INT EXT_CALLBACK ColorResCallback (pBITMAPHANDLE pBitmap, 
                                       L_UCHAR  *pBuffer, L_INT nLines, 
                                       L_VOID * pColorResUserData);

 L_INT ColorResBitmapExample(HWND hWnd,
                                            HINSTANCE    hInst,   /* Current instance of the application, set by the InitInstance function */
                                            pBITMAPHANDLE LeadBitmap   /* Bitmap handle to hold the loaded image */,
                                            HPALETTE hpalPaint, /* Paint palette handle */
                                            RECT *rLeadDest, /* Destination rectangle for painting */ 
                                            RECT *rLeadSource /* Source rectangle for painting */)
{
   L_INT nRet;
   IMAGECBPARM      UserData; /* Structure used for the callback function's user data */
   COLORRESCALLBACK lpfnColorCallBack;

   UserData.hpalPaint = hpalPaint;
   UserData.rLeadDest   = *rLeadDest ;
   UserData.rLeadSource = *rLeadSource;
   UNREFERENCED_PARAMETER(hInst);
   /* Set the user data used for the callback in the L_ColorResBitmap function */
   UserData.hwnd = hWnd;         /* Current window */
   UserData.hdc = GetDC( hWnd ); /* Device context for the current window */
   UserData.nRow = 0;            /* First row in the buffer for the callback function */
   /* Set the callback function for the L_ColorResBitmap function.*/
   lpfnColorCallBack = (COLORRESCALLBACK) MakeProcInstance((FARPROC) ColorResCallback, hInst );

   /* Change the color resolution to 4 bits per pixel using and optimized palette and
   with a callback function that paints the image as it is processed */
   nRet = L_ColorResBitmap(LeadBitmap,LeadBitmap, sizeof(BITMAPHANDLE), 4,
                           CRF_FLOYDSTEINDITHERING|CRF_OPTIMIZEDPALETTE, 
                           NULL, NULL, 0, lpfnColorCallBack, &UserData );
   if(nRet != SUCCESS)
      return nRet;
   FreeProcInstance ((FARPROC) lpfnColorCallBack);

   /* Avoid an unnecessary repaint */
   ValidateRect(hWnd, rLeadDest);

   return SUCCESS;
}