Bitmap.ConvertFormat method

Applies to: desktop apps only

The Bitmap::ConvertFormat method converts a bitmap to a specified pixel format. The original pixel data in the bitmap is replaced by the new pixel data.


Status ConvertFormat(
  [in]  PixelFormat format,
  [in]  DitherType dithertype,
  [in]  PaletteType palettetype,
  [in]  ColorPalette *palette,
  [in]  REAL alphaThresholdPercent


format [in]

Type: PixelFormat

Pixel format constant that specifies the new pixel format.

dithertype [in]

Type: DitherType

Element of the DitherType enumeration that specifies the dithering algorithm. In cases where the conversion does not reduce the bit depth of the pixel data, pass DitherTypeNone.

palettetype [in]

Type: PaletteType

Element of the PaletteType enumeration that specifies a standard palette to be used for dithering. If you are converting to a non-indexed format, this parameter is ignored. In that case, pass any element of the PaletteType enumeration, say PaletteTypeCustom.

palette [in]

Type: ColorPalette*

Pointer to a ColorPalette structure that specifies the palette whose indexes are stored in the pixel data of the converted bitmap. This palette (called the actual palette) does not have to have the type specified by the palettetype parameter. The palettetype parameter specifies a standard palette that can be used by any of the ordered or spiral dithering algorithms. If the actual palette has a type other than that specified by the palettetype parameter, then the Bitmap::ConvertFormat method performs a nearest-color conversion from the standard palette to the actual palette.

alphaThresholdPercent [in]

Type: REAL

Real number in the range 0 through 100 that specifies which pixels in the source bitmap will map to the transparent color in the converted bitmap. A value of 0 specifies that none of the source pixels map to the transparent color. A value of 100 specifies that any pixel that is not fully opaque will map to the transparent color. A value of t specifies that any source pixel less than t percent of fully opaque will map to the transparent color. Note that for the alpha threshold to be effective, the palette must have a transparent color. If the palette does not have a transparent color, pixels with alpha values below the threshold will map to color that most closely matches (0, 0, 0, 0), usually black.

Return value


Type: Status

If the method succeeds, it returns Ok, which is an element of the Status enumeration.

If the method fails, it returns one of the other elements of the Status enumeration.


The following example converts a bitmap to an indexed format based on a standard fixed palette.

VOID Example_ConvertFormat(HDC hdc)
   Graphics graphics(hdc);
   Bitmap myBitmap(L"Photo.jpg");
   INT width = myBitmap.GetWidth();
   INT height = myBitmap.GetHeight();

   graphics.DrawImage(&myBitmap, 20, 20, width, height);

   // PaletteTypeFixedHalftone27 has 36 entries. A ColorPalette structure has
   // room for one entry, so space is allocated for an additional 35 entries.
   ColorPalette* pal = (ColorPalette*)malloc(sizeof(ColorPalette) + 35*sizeof(ARGB));
   pal->Count = 36;
   pal->Flags = 0;
   Bitmap::InitializePalette(pal, PaletteTypeFixedHalftone27, 0, TRUE, NULL); 


   graphics.DrawImage(&myBitmap, width + 40, 20, width, height);



Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2008


GDI+ 1.1


GdiplusBitmap.h (include Gdiplus.h)





See also




Send comments about this topic to Microsoft

Build date: 3/6/2012

Community Additions