Add support for converting the format of a Bitmap

Background

GDI+ 1.1 added support for converting the pixel format of an bitmap in-place. Naturally, one can specify a target pixel format, but the function accepts many other parameters to control aspects of the conversion. Unfortunately, the API is not very well designed — it’s poorly documented, and many combinations of options seem to be outright ignored or result in vague errors — but a not insubstantial amount of people have wondered how to do this, and the workaround is slow, less flexible, and certainly not obvious.

When converting to an indexed pixel format, the ditherType, paletteType, and palette parameters become relevant. Color palettes can be provided in order to constrain the colors in the converted image. There are effectively three categories of palettes:

• Custom palettes. All available colors are specified by the user.
• Optimal palettes. An optimal palette is created using an image, and consists of the best n colors (where n is specified by the user) from the image to be used when converting the image.
• Standard palettes. The user can specify one of many predefined fixed palettes, and may use them in combination with an ordered or spiral dither type to produce a halftone image.

When a standard fixed palette type is used, any dither type is valid. Otherwise, only None, Solid, and ErrorDiffusion are valid. (As an exception, DitherTypeOrdered4x4 may be used when converting to a 16 bits-per-pixel format using any palette.) GDI+ will convert from a standard palette specified with paletteType to a custom palette passed in palette using a nearest-color conversion.

One can also specify an alpha threshold percent. Passing a value t specifies that a pixel that is less than t percent fully opaque will map to the transparent color. (If there is no transparent color, the color closest to black will be selected.)

This proposal is one of many to add missing GDI+ 1.1 functionality to System.Drawing.

Usage Example

Bitmap bitmap = (Bitmap) Image.FromFile("immo.jpg");
ColorPalette palette = new ColorPalette(PaletteType.FixedHalftone8);
image.ConvertFormat(PixelFormat.Format8bppIndexed, DitherType.Ordered16x16, PaletteType.FixedHalftone8, palette);

API Proposal

See the documentation for:

• Bitmap::ConvertFormat
• Bitmap::InitializePalette
• DitherType
• PaletteType

namespace System.Drawing.Imaging
{
+   public enum PaletteType
+   {
+       Custom,
+       Optimal,
+       FixedBW,
+       FixedHalftone8,
+       FixedHalftone27,
+       FixedHalftone64,
+       FixedHalftone125,
+       FixedHalftone216,
+       FixedHalftone252,
+       FixedHalftone256
+   }
    
+   public enum DitherType
+   {
+       None,
+       Solid,
+       ErrorDiffusion,
+       Ordered4x4,
+       Ordered8x8,
+       Ordered16x16,
+       Spiral4x4,
+       Spiral8x8,
+       DualSpiral4x4,
+       DualSpiral8x8
+   }

    public sealed class ColorPalette
    {
+       public ColorPalette(Color[] customColors);
+       public ColorPalette(PaletteType fixedPaletteType);
+       public static ColorPalette CreateOptimalPalette(int colors, Bitmap bitmap);
    }
}

namespace System.Drawing
{
    public sealed class Bitmap : System.Drawing.Image
    {
!       Overload for simplicity.
+       public void ConvertFormat(PixelFormat format);
+       public void ConvertFormat(PixelFormat format, DitherType ditherType, PaletteType paletteType, ColorPalette? palette, float alphaThresholdPercent);
    }
}

This requires changes to libgdiplus in order to support it on non-Windows platforms.

[reflectronic]

What would the story for Unix be?

Setting myself up for a lot of work to contribute to libgdiplus 😃

[safern]

Thanks, @reflectronic. Sure I will. I will mark these issues 7.0.0 for now so that we review them for .NET 7.