ImageExtensionsConvertPixelFormat(Image, PixelFormat, Color, Color, Byte) Method

Converts the specified image to a Bitmap of the desired PixelFormat.

Definition

Namespace: KGySoft.Drawing
Assembly: KGySoft.Drawing (in KGySoft.Drawing.dll) Version: 8.1.0
C#
public static Bitmap ConvertPixelFormat(
	this Image image,
	PixelFormat newPixelFormat,
	Color[]? palette,
	Color backColor = default,
	byte alphaThreshold = 128
)

Parameters

image  Image
The original image to convert.
newPixelFormat  PixelFormat
The desired new pixel format.
palette  Color
The desired target palette if newPixelFormat is an indexed format. If , then the source palette is taken from the source image if it also has a palette of no more entries than the target indexed format can have; otherwise, a default palette will be used based on newPixelFormat.
backColor  Color  (Optional)
If newPixelFormat does not support alpha or supports 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

Bitmap
A new Bitmap instance with the desired pixel format.

Usage Note

In Visual Basic and C#, you can call this method as an instance method on any object of type Image. When you use instance method syntax to call this method, omit the first parameter. For more information, see Extension Methods (Visual Basic) or Extension Methods (C# Programming Guide).

Remarks

  Note

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.

If newPixelFormat is Format8bppIndexed, image has no palette and palette is , then the standard 256 color palette will be used. On Windows this contains the web-safe palette, the standard 16 Windows colors and the transparent color.

If newPixelFormat is Format4bppIndexed, image has no palette and palette is , then the standard 16 color palette will be used.

If newPixelFormat is Format1bppIndexed, image has no palette and palette is , then black and white colors will be used.

Example

The following example demonstrates the possible results of this method:
C#
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");

    // Specifying a custom palette of 8 colors
    Color[] palette =
    {
        Color.Black, Color.Red, Color.Lime, Color.Blue,
        Color.Magenta, Color.Yellow, Color.Cyan, Color.White
    };

    // Palette is ignored for hi-color and true-color formats
    using (Bitmap converted24Bpp = original.ConvertPixelFormat(PixelFormat.Format24bppRgb, palette))
        converted24Bpp.SaveAsPng(@"c:\temp\24bpp.png");

    // But it is considered if converting to an indexed format.
    // Alpha pixels will be blended with Color.Silver.
    using (Bitmap converted8Bpp = original.ConvertPixelFormat(PixelFormat.Format8bppIndexed, palette, Color.Silver))
        converted8Bpp.SaveAsGif(@"c:\temp\8bpp custom palette.gif");
}

The example above produces the following results:

original.png32 BPP shield icon with transparent background
24bpp.png24 BPP shield icon with black background
8bpp custom palette.gif8-color (RGB111) shield icon with silver background. Without dithering the background turned white.

Exceptions

ArgumentNullExceptionimage is .
ArgumentOutOfRangeExceptionnewPixelFormat is out of the defined values.
ArgumentExceptionpalette contains too many colors for the indexed format specified by newPixelFormat.
PlatformNotSupportedExceptionnewPixelFormat is not supported on the current platform.

See Also