LBitmapBase::ColorRes

#include "ltwrappr.h"

virtual L_INT LBitmapBase::ColorRes(nBitsPerPixel, uFlags=CRF_FIXEDPALETTE|CRF_FLOYDSTEINDITHERING, pPalette=NULL, hPalette=NULL, uColors=0)

virtual L_INT LBitmapBase::ColorRes(BitmapSrc, nBitsPerPixel, uFlags=CRF_FIXEDPALETTE|CRF_FLOYDSTEINDITHERING, pPalette=NULL, hPalette=NULL, uColors=0)

Converts a class objects bitmap from any bits-per-pixel to any bits-per-pixel.

Parameters

L_INT 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.

L_UINT32 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 ( | ). Possible values are:

LPRGBQUAD 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.
• 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 palettein pPalette and NULL in hPalette.

HPALETTE 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.
• 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.

L_UINT 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.

LBitmapBase& BitmapSrc

The source bitmap on which the conversion will be done.

Returns

Comments

Call this function to do a color resolution on the source class object's bitmap and place the result in the calling object's bitmap. Note that if the callback functions are enabled, then the LBitmapBase::ColorResBitmapCallBack function of the calling object will be called for the color resolution operation.

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 LBitmapSettings::CreateUserMatchTable.

Note: The BitmapSrc parameter is passed by reference, and is a required parameter.

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.

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 supports stripping the alpha channel from the image.

Required DLLs and Libraries

• LTDIS
• LTFIL
• 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::ColorResBitmapCallBack
• LBase::EnableCallBack
• LBase::IsCallBackEnabled
• LBitmap::AutoBinarize
• LBitmap::DynamicBinary
• LBitmap::AutoBinary
• Class Members

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

This example is for LBitmapBase::ColorRes(BitmapSrc, nBitsPerPixel, uFlags, pPalette, hPalette, uColors):

L_INT LBitmapBase__ColorResExample() 
{ 
   L_INT nRet; 
   LBitmapBase MyBitmap,Bitmap2; 
 
   nRet =MyBitmap.Load(MAKE_IMAGE_PATH(TEXT("image1.cmp")),24); 
   if(nRet !=SUCCESS) 
      return nRet; 
 
   nRet =Bitmap2.ColorRes(MyBitmap, 8,CRF_FIXEDPALETTE|CRF_FLOYDSTEINDITHERING); 
   if(nRet !=SUCCESS) 
      return nRet; 
 
 
   return SUCCESS; 
}