ImageExtensionsConvertPixelFormat(Image, PixelFormat, Color, Byte) Method
Namespace: KGySoft.DrawingAssembly: KGySoft.Drawing (in KGySoft.Drawing.dll) Version: 7.2.0
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
- 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.
BitmapA new
Bitmap instance with the desired pixel format.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).
- This method adjusts the degree of parallelization automatically, blocks the caller, and does not support cancellation or reporting progress. Use the BeginConvertPixelFormat(Image, PixelFormat, Color, Byte, AsyncConfig)
or ConvertPixelFormatAsync(Image, 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(Bitmap, WorkingColorSpace, Color, Byte) on
a Bitmap instance, and then call the ToBitmap extension method.
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.
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).
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 Format | Windows Support | Linux Support |
---|
Format1bppIndexed | | |
Format4bppIndexed | | |
Format8bppIndexed | | |
Format16bppGrayScale | | On 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. |
- 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.
To convert an image to any
PixelFormat on any platform obtain an
IReadWriteBitmapData from a
Bitmap by
the
GetReadWriteBitmapData extension method and use
the
Clone extension methods.