ImageExtensionsConvertPixelFormat(Image, PixelFormat, Color, Byte) Method

public static Bitmap ConvertPixelFormat(
	this Image image,
	PixelFormat newPixelFormat,
	Color backColor = default,
	byte alphaThreshold = 128
)

<ExtensionAttribute>
Public Shared Function ConvertPixelFormat ( 
	image As Image,
	newPixelFormat As PixelFormat,
	Optional backColor As Color = Nothing,
	Optional alphaThreshold As Byte = 128
) As Bitmap

public:
[ExtensionAttribute]
static Bitmap^ ConvertPixelFormat(
	Image^ image, 
	PixelFormat newPixelFormat, 
	Color backColor = Color(), 
	unsigned char alphaThreshold = 128
)

[<ExtensionAttribute>]
static member ConvertPixelFormat : 
        image : Image * 
        newPixelFormat : PixelFormat * 
        ?backColor : Color * 
        ?alphaThreshold : byte 
(* Defaults:
        let _backColor = defaultArg backColor new Color()
        let _alphaThreshold = defaultArg alphaThreshold 128
*)
-> Bitmap 

Parameters

image  Image

The original image to convert.

newPixelFormat  PixelFormat

The desired new pixel format.

backColor  Color  (Optional)

If newPixelFormat does not have alpha or has only single-bit alpha, then specifies the color of the background. Source pixels with alpha, which will be opaque in the result will be blended with this color. The Color.A property of the background color is ignored. This parameter is optional.
Default value: Empty, which has the same RGB values as Black.

alphaThreshold  Byte  (Optional)

If newPixelFormat can represent only single-bit alpha or newPixelFormat is an indexed format and the target palette contains a transparent color, then specifies a threshold value for the Color.A property, under which the color is considered transparent. If 0, then the result will not have transparent pixels. This parameter is optional.
Default value: 128.

Return Value

Usage Note

If newPixelFormat is an indexed format, then this overload will either use the palette of the source image if applicable, or a system default palette. To apply a custom palette use the of the ConvertPixelFormat(Image, PixelFormat, Color, Color, Byte) overload.

If newPixelFormat can represent fewer colors than the source format, then a default quantization will occur during the conversion. To use a specific quantizer (and optionally a ditherer) use the ConvertPixelFormat(Image, PixelFormat, IQuantizer, IDitherer) overload. To use a quantizer with a specific palette you can use the PredefinedColorsQuantizer class.

Restrictions of Possible Pixel Formats on Different Platforms

The support of Bitmaps with different PixelFormats may vary from platform to platform. Though the types in KGySoft Drawing Libraries support every PixelFormat the standard System.Drawing libraries has some restrictions. The following table summarizes the levels of support for Windows and Linux/Unix systems (applicable both for Mono and .NET Core if libgdiplus is installed).

using (Bitmap original = Icons.Shield.ExtractBitmap(new Size(256, 256)))
{
    // The original bitmap has 32 bpp color depth with transparency
    original.SaveAsPng(@"c:\temp\original.png");

    // 24 BPP format has no transparency. If backColor is not specified the background will be black.
    using (Bitmap converted24BppBlack = original.ConvertPixelFormat(PixelFormat.Format24bppRgb))
        converted24BppBlack.SaveAsPng(@"c:\temp\24 bpp black.png");

    // Using Color.Cyan as backColor. Source pixels with alpha will be blended with this color.
    using (Bitmap converted24BppCyan = original.ConvertPixelFormat(PixelFormat.Format24bppRgb, Color.Cyan))
        converted24BppCyan.SaveAsPng(@"c:\temp\24 bpp cyan.png");

    // Converting to 16 BPP grayscale. The cyan back color will be a light gray shade in the result.
    // As a PNG will be saved as a 24 BPP image.
    using (Bitmap converted16Bpp = original.ConvertPixelFormat(PixelFormat.Format16bppGrayScale, Color.Cyan))
        converted16Bpp.SaveAsPng(@"c:\temp\16bpp grayscale.png");

    // The default 8 BPP palette has the transparent color. The default values (backColor = Color.Black,
    // alphaThreshold = 128) specify that source pixels with alpha < 128 will be transparent
    // and alpha >= 1 will be blended with Color.Black.
    using (Bitmap converted8Bpp = original.ConvertPixelFormat(PixelFormat.Format8bppIndexed))
        converted8Bpp.SaveAsGif(@"c:\temp\default 8 bpp palette.gif");
}

The example above produces the following results:

original.png
24 bpp black.png
24 bpp cyan.png
16 bpp grayscale.png
default 8 bpp palette.gif

Reference