ImageExtensionsConvertPixelFormat(Image, PixelFormat, 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: 7.2.0
C#
public static Bitmap ConvertPixelFormat(
	this Image image,
	PixelFormat newPixelFormat,
	Color backColor = default,
	byte alphaThreshold = 128
)

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

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 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).

  Note

When targeting .NET 7 or later System.Drawing types backed by GDI+ components (types defined in the System.Drawing.Common package) are no longer supported on Linux/Unix systems.
When targeting .NET 5 or 6 see also the Remarks section of the DrawingModule.Initialize method.
Pixel FormatWindows SupportLinux Support
Format1bppIndexed
Format4bppIndexed
Format8bppIndexed
Format16bppGrayScaleOn Linux a Bitmap cannot be instantiated with this pixel format.
Format16bppRgb555
  • The SaveAs... members of the ImageExtensions class support saving into any popular format but pixel format will not be preserved.
Format16bppRgb565
  • The SaveAs... members of the ImageExtensions class support saving into any popular format but pixel format will not be preserved.
Format16bppArgb1555
  • Graphics.FromImage is not supported.
  • The SaveAs... members of the ImageExtensions class support saving into any popular format but pixel format will not be preserved.
On Linux a Bitmap cannot be instantiated with this pixel format.
Format24bppRgb
  • This format is fully supported also by System.Drawing.
  • Saving as anything but GIF preserves the pixel format.
  • This format is fully supported also by System.Drawing.
  • Saving as anything but GIF preserves the pixel format.
Format32bppRgb
  • This format is fully supported also by System.Drawing.
  • Saving as BMP preserves the pixel format but loss of transparency occurs when saving as JPEG, PNG or TIFF.
  • This format is fully supported also by System.Drawing.
  • Saving as BMP preserves the pixel format but loss of transparency occurs when saving as JPEG, PNG or TIFF.
Format32bppArgb
  • This format is fully supported also by System.Drawing.
  • Saving as PNG or TIFF (as well as Icon) preserves the pixel format.
  • This format is fully supported also by System.Drawing.
  • Saving as PNG or TIFF (as well as Icon) preserves the pixel format.
Format32bppPArgb
  • This format is fully supported also by System.Drawing.
  • Saving as PNG or TIFF (as well as Icon) preserves possible alpha information but the pixel format will turn Format32bppArgb when the image is reloaded.
  • This format is fully supported also by System.Drawing.
  • Saving as PNG or TIFF by the ImageExtensions members preserves possible alpha information correctly but the pixel format will turn Format32bppArgb when the image is reloaded. Saving the image by Image.Save members corrupts alpha information.
Format48bppRgb
  • This format is fully supported also by System.Drawing, though all processing, displaying and saving operations convert pixel information to 8 bit-per-channel colors.
  • The SaveAs... members of the ImageExtensions class support saving into any popular format but pixel format will not be preserved, except if the image was already a Bitmap with TIFF raw format (though the color information might be quantized to a 13 bit-per-channel range also in this case).
  • To read and write the actual data without losing information use the IWritableBitmapDataRow.WriteRaw and IReadableBitmapDataRow.ReadRaw methods (see also the note below).
On Linux a Bitmap cannot be instantiated with this pixel format.
Format64bppArgb
  • This format is fully supported also by System.Drawing, though all processing, displaying and saving operations convert pixel information to 8 bit-per-channel colors.
  • The SaveAs... members of the ImageExtensions class support saving into any popular format but pixel format will not be preserved. To preserve (a possible quantized) alpha information save the image as PNG or TIFF.
  • To read and write the actual data without losing information use the IWritableBitmapDataRow.WriteRaw and IReadableBitmapDataRow.ReadRaw methods (see also the note below).
On Linux a Bitmap cannot be instantiated with this pixel format.
Format64bppPArgb
  • This format is fully supported also by System.Drawing, though all processing, displaying and saving operations convert pixel information to 8 bit-per-channel colors.
  • The SaveAs... members of the ImageExtensions class support saving into any popular format but pixel format will not be preserved. To preserve (a possible quantized) alpha information save the image as PNG or TIFF.
  • To read and write the actual data without losing information use the IWritableBitmapDataRow.WriteRaw and IReadableBitmapDataRow.ReadRaw methods (see also the note below).
On Linux a Bitmap cannot be instantiated with this pixel format.

  Note

  • On Windows Format48bppRgb, Format64bppArgb and Format64bppPArgb formats (hereinafter: wide formats) actually use 13 bit-per-channel colors internally (values between 0 and 8192, inclusively). The mapping between the 8 and 16 bit color channels is not linear: whereas the Color (and also Color32) structures represent colors with gamma correction γ = 2.2, the wide formats have no gamma correction (γ = 1.0).
  • If wide color formats are supported on the current operating system, then KGySoft Drawing Libraries auto detects the used range and gamma correction. For example, if the libgdiplus library will support them on Linux, then IWritableBitmapData and IReadableBitmapData members will always use the correct transformations automatically.
  • .NET Framework 4.0 is supported on ReactOS, which uses the full 16-bit range with linear mapping between wide and narrow color channels the same way it's used at KGy SOFT's KnownPixelFormat.
  • If you want to manipulate wide colors without losing information you can use the IWritableBitmapDataRow.WriteRaw and IReadableBitmapDataRow.ReadRaw methods. As these methods provide access to the raw underlying data it is your responsibility to know what ranges and values are used for a specific PixelFormat on the current operating system.
  • The KGySoft Drawing Libraries use the full 16-bit range of values for the Format16bppGrayScale format and the transformation is linear between the 8 and 16 bit shades on every platform that supports this format.

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");

    // 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.png32 BPP shield icon with transparent background
24 bpp black.png24 BPP shield icon with black background
24 bpp cyan.png24 BPP shield icon with cyan background
16 bpp grayscale.png16 BPP grayscale shield icon with cyan background. The cyan color turned light gray.
default 8 bpp palette.gif8 BPP shield icon with system default palette

Exceptions

ArgumentNullExceptionimage is .
ArgumentOutOfRangeExceptionnewPixelFormat is out of the defined values.
PlatformNotSupportedExceptionnewPixelFormat is not supported on the current platform.

See Also