BitmapSourceExtensionsConvertPixelFormat(BitmapSource, PixelFormat, Color, Byte) Method

Converts the specified bitmap to a WriteableBitmap of the desired PixelFormat.

Definition

Namespace: KGySoft.Drawing.Wpf
Assembly: KGySoft.Drawing.Wpf (in KGySoft.Drawing.Wpf.dll) Version: 10.0.0-rc.1

public static WriteableBitmap ConvertPixelFormat(
	this BitmapSource bitmap,
	PixelFormat newPixelFormat,
	Color backColor = default,
	byte alphaThreshold = 128
)

<ExtensionAttribute>
Public Shared Function ConvertPixelFormat ( 
	bitmap As BitmapSource,
	newPixelFormat As PixelFormat,
	Optional backColor As Color = Nothing,
	Optional alphaThreshold As Byte = 128
) As WriteableBitmap

C++

public:
[ExtensionAttribute]
static WriteableBitmap^ ConvertPixelFormat(
	BitmapSource^ bitmap, 
	PixelFormat newPixelFormat, 
	Color backColor = Color(), 
	unsigned char alphaThreshold = 128
)

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

Parameters

bitmap BitmapSource: The original bitmap to convert.
newPixelFormat PixelFormat: The desired new pixel format.
backColor Color (Optional): If newPixelFormat does not have 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: The bitwise zero instance of Color, which has the same RGB values as Black.
alphaThreshold Byte (Optional): If 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

WriteableBitmap
A new WriteableBitmap 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 BitmapSource. 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

This method adjusts the degree of parallelization automatically, blocks the caller, and does not support cancellation or reporting progress. Use the BeginConvertPixelFormat(BitmapSource, PixelFormat, Color, Byte, AsyncConfig) or ConvertPixelFormatAsync(BitmapSource, PixelFormat, Color, Byte, TaskConfig) (in .NET Framework 4.0 and above) methods for asynchronous call and to adjust parallelization, set up cancellation and for reporting progress.
If newPixelFormat requires blending with backColor, then this method selects the working color space automatically. To apply a specific color space use the GetReadableBitmapData(BitmapSource, WorkingColorSpace, Color, Byte) on a BitmapSource instance, and then call the ToWriteableBitmap extension method.

If newPixelFormat is an indexed format, then this overload will either use the palette of the source bitmap if applicable, or a default palette. To apply a custom palette use the of the ConvertPixelFormat(BitmapSource, 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(BitmapSource, PixelFormat, IQuantizer, IDitherer) overload. To use a quantizer with a specific palette you can use the PredefinedColorsQuantizer class.

Examples

The following example demonstrates the possible results of this method compared to using WPF's FormatConvertedBitmap class:

public static BitmapSource Convert(BitmapSource source, PixelFormat targetPixelFormat, Color backColor, byte alphaThreshold)
{
    // a.) by KGy SOFT: can use a back color, handles alpha correctly, uses a default palette for indexed formats.
    //     (to use specific quantizer or ditherer you can use an other overload)
    return source.ConvertPixelFormat(targetPixelFormat, backColor, alphaThreshold);

    // b.) by WPF: no back color is used, alpha colors above the threshold suffer from color bleeding,
    //     can use an optimized palette for indexed formats, a fixed dithering is forcibly used for <= 8 bpp formats
    return new FormatConvertedBitmap(source, targetPixelFormat, GetDefaultPalette(), alphaThreshold / 255d * 100d);

    // Using the same colors for the WPF conversion as KGy SOFT conversion uses.
    BitmapPalette? GetDefaultPalette() =>
        source.Palette != null && source.Format.BitsPerPixel <= targetPixelFormat.BitsPerPixel ? source.Palette
        : targetPixelFormat == PixelFormats.Indexed1 ? ToBitmapPalette(Palette.SystemDefault1BppPalette())
        : targetPixelFormat == PixelFormats.Indexed2 ? new BitmapPalette(new[] { Colors.Black, Colors.Gray, Colors.Silver, Colors.White })
        : targetPixelFormat == PixelFormats.Indexed4 ? ToBitmapPalette(Palette.SystemDefault4BppPalette())
        : targetPixelFormat == PixelFormats.Indexed8 ? ToBitmapPalette(Palette.SystemDefault8BppPalette())
        : null;

    static BitmapPalette ToBitmapPalette(Palette palette)
        => new BitmapPalette(palette.GetEntries().Select(c => Color.FromArgb(c.A, c.R, c.G, c.B)).ToList());
}

Original image	Converted image
Color hues with alpha gradient	Using ConvertPixelFormat with Indexed8 format, white background, alpha threshold = 16. This overload does not use dithering, the bottom 16 rows are transparent, the alpha pixels above were blended with white. Using WPF's FormatConvertedBitmap with the same parameters as above. The result is forcibly dithered and the alpha pixels above the threshold were not blended with any back color so the vertical gradient has just been disappeared.
Shield icon with transparency	Using ConvertPixelFormat with Rgb24 format, silver background. The alpha pixels were blended with the silver color (alpha threshold is ignored because this format does not support alpha). Using WPF's FormatConvertedBitmap with the same parameters as above. The alpha pixels just turned opaque without blending them with any color. Some light pixels appeared where RGB values of the alpha pixels were not completely black.

Original image

Converted image

Color hues with alpha gradient

Alpha gradient converted to indexed 8 bit format by KGy SOFT conversion using default palette, white background, alpha threshold is 16
Using ConvertPixelFormat with Indexed8 format, white background, alpha threshold = 16. This overload does not use dithering, the bottom 16 rows are transparent, the alpha pixels above were blended with white.

Alpha gradient converted to indexed 8 bit format by FormatConvertedBitmap
Using WPF's FormatConvertedBitmap with the same parameters as above. The result is forcibly dithered and the alpha pixels above the threshold were not blended with any back color so the vertical gradient has just been disappeared.

Shield icon with transparent background
Shield icon with transparency

Shield icon with silver background
Using ConvertPixelFormat with Rgb24 format, silver background. The alpha pixels were blended with the silver color (alpha threshold is ignored because this format does not support alpha).

Shield icon converted to RGB24 format by FormatConvertedBitmap
Using WPF's FormatConvertedBitmap with the same parameters as above. The alpha pixels just turned opaque without blending them with any color. Some light pixels appeared where RGB values of the alpha pixels were not completely black.

Exceptions

ArgumentNullException	bitmap is .
ArgumentOutOfRangeException	newPixelFormat does not specify a valid format.
InvalidOperationException	A deadlock has been detected while attempting to create the result.