Bitmap::ConvertFormat method (gdiplusheaders.h)

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


[in] format

Type: PixelFormat

Pixel format constant that specifies the new pixel format.

[in] dithertype

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.

[in] palettetype

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.

[in] palette

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.

[in] alphaThresholdPercent

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.


Requirement Value
Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header gdiplusheaders.h (include Gdiplus.h)
Library Gdiplus.lib
DLL Gdiplus.dll

See also