ImageExtensionsConvertPixelFormat(Image, PixelFormat, Color, Color, Byte) Method
Namespace: KGySoft.DrawingAssembly: KGySoft.Drawing (in KGySoft.Drawing.dll) Version: 9.0.0
public static Bitmap ConvertPixelFormat(
this Image image,
PixelFormat newPixelFormat,
Color[]? palette,
Color backColor = default,
byte alphaThreshold = 128
)
<ExtensionAttribute>
Public Shared Function ConvertPixelFormat (
image As Image,
newPixelFormat As PixelFormat,
palette As Color(),
Optional backColor As Color = Nothing,
Optional alphaThreshold As Byte = 128
) As Bitmap
public:
[ExtensionAttribute]
static Bitmap^ ConvertPixelFormat(
Image^ image,
PixelFormat newPixelFormat,
array<Color>^ palette,
Color backColor = Color(),
unsigned char alphaThreshold = 128
)
[<ExtensionAttribute>]
static member ConvertPixelFormat :
image : Image *
newPixelFormat : PixelFormat *
palette : Color[] *
?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.
- 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.
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, Color, Byte, AsyncConfig)
or ConvertPixelFormatAsync(Image, PixelFormat, Color, 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 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.
For information about the possible usable
PixelFormats on different platforms see the
Remarks section of the
ConvertPixelFormat(Image, PixelFormat, Color, Byte) overload.
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.
The following example demonstrates the possible results of this method:
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.png |  |
| 24bpp.png |  |
| 8bpp custom palette.gif |  |
